Forem

Cover image for ¿Cómo Usar APIs de Azure?
Roobia
Roobia

Posted on • Originally published at apidog.com

¿Cómo Usar APIs de Azure?

TL;DR

Las API de Azure permiten el acceso programático a los servicios en la nube de Microsoft: almacenamiento, computación, bases de datos, IA y más. Se autentica usando Azure Active Directory (Entra ID), obtiene un token de acceso y hace llamadas a los endpoints REST. Para pruebas y documentación, use Apidog para guardar sus llamadas, validar respuestas contra esquemas y compartir colecciones con su equipo.

Prueba Apidog hoy mismo

Introducción

Microsoft Azure ofrece más de 200 servicios, cada uno con su propia API. Como desarrollador, probablemente necesitará interactuar con algunos de estos servicios, como Azure Blob Storage para archivos, Azure Functions para serverless o Azure OpenAI para modelos LLM.

El mayor reto es la documentación: es extensa y dispersa, lo que puede hacer perder tiempo buscando endpoints, configurando la autenticación adecuada y depurando errores como 401 Unauthorized.

Esta guía se enfoca en las API más relevantes para proyectos reales — no en los 200 servicios, sino en los 5-10 que impulsan la mayoría de las aplicaciones. Aprenderá cómo implementar la autenticación, resolver errores frecuentes y probar integraciones con Azure antes del despliegue.

💡 Tip: Si desarrolla con APIs de Azure, Apidog le ayuda a diseñar, probar y documentar integraciones. Puede guardar sus llamadas como colecciones, usar variables de entorno para diferentes suscripciones y validar respuestas contra esquemas. Así detecta errores de configuración antes de producción.

Al finalizar esta guía, podrá:

  • Configurar la autenticación de Azure correctamente (el error más común)
  • Llamar a las API de Azure Storage, Compute y AI con ejemplos prácticos
  • Depurar errores comunes de la API de Azure
  • Probar y documentar sus integraciones de Azure con Apidog

El problema de la autenticación (y cómo resolverlo)

Cada llamada a la API de Azure requiere autenticación. Si la configuración es incorrecta, todo lo demás falla. Es el principal punto de bloqueo para muchos desarrolladores.

Azure Auth Flow

Azure Active Directory / Microsoft Entra ID

Azure utiliza OAuth 2.0 para autenticar llamadas a las API. No se envía usuario y contraseña, sino un token de acceso que prueba identidad y permisos.

Flujo básico:

  1. Registre una aplicación en Azure AD (Entra ID)
  2. Obtenga un ID de cliente y un secreto de cliente
  3. Solicite un token de acceso al endpoint de Azure
  4. Incluya el token en cada solicitud a la API

Paso 1: Registrar una aplicación

  • Azure Portal → Microsoft Entra ID → Registros de aplicaciones → Nuevo registro
  • Nombre la app, seleccione "Cuentas en este directorio organizacional solamente" y regístrela
  • Obtendrá:
    • ID de aplicación (cliente): 12345678-1234-1234-1234-123456789abc
    • ID de directorio (inquilino): 87654321-4321-4321-4321-cba987654321

Paso 2: Crear un secreto de cliente

  • En el registro de la app: Certificados y secretos → Nuevo secreto de cliente
  • Copie el valor del secreto inmediatamente (no podrá volver a verlo)
    • Secreto de cliente: abc123~DEF456-ghi789

Paso 3: Asignar permisos

  • Permisos de API → Agregar un permiso
    • Para Storage: "Azure Storage" → "user_impersonation"
    • Para administración: "Azure Service Management" → "user_impersonation"

Paso 4: Obtener un token de acceso

curl -X POST "https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={client-id}" \
  -d "client_secret={client-secret}" \
  -d "scope=https://storage.azure.com/.default" \
  -d "grant_type=client_credentials"
Enter fullscreen mode Exit fullscreen mode

Respuesta:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs...",
  "expires_in": 3599,
  "token_type": "Bearer"
}
Enter fullscreen mode Exit fullscreen mode

Paso 5: Usar el token

curl -X GET "https://youraccount.blob.core.windows.net/container?restype=container&comp=list" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIs..." \
  -H "x-ms-version: 2023-01-03"
Enter fullscreen mode Exit fullscreen mode

Uso del SDK de Azure en vez de HTTP puro

Para código de producción, use el SDK de Azure: gestiona la actualización de tokens, reintentos y serialización.

import { DefaultAzureCredential } from '@azure/identity'
import { BlobServiceClient } from '@azure/storage-blob'

// Usa automáticamente el inicio de sesión de Azure CLI o variables de entorno
const credential = new DefaultAzureCredential()
const blobServiceClient = new BlobServiceClient(
  'https://youraccount.blob.core.windows.net',
  credential
)

// Listar contenedores
for await (const container of blobServiceClient.listContainers()) {
  console.log(container.name)
}
Enter fullscreen mode Exit fullscreen mode

Pero para probar, depurar y documentar, es fundamental entender las llamadas HTTP directas. Ahí es donde Apidog resulta útil.

API de Azure Storage

Azure Storage es uno de los servicios más utilizados e incluye:

  • Blob Storage: Archivos, imágenes, backups
  • Queue Storage: Colas de mensajes
  • Table Storage: Almacén NoSQL clave-valor
  • File Storage: Comparticiones SMB

API de Blob Storage

Listar contenedores:

GET https://{account}.blob.core.windows.net/?comp=list
Authorization: Bearer {token}
x-ms-version: 2023-01-03
Enter fullscreen mode Exit fullscreen mode

Crear un contenedor:

PUT https://{account}.blob.core.windows.net/{container}?restype=container
Authorization: Bearer {token}
x-ms-version: 2023-01-03
Enter fullscreen mode Exit fullscreen mode

Subir un blob:

PUT https://{account}.blob.core.windows.net/{container}/{blob}
Authorization: Bearer {token}
x-ms-version: 2023-01-03
Content-Type: text/plain

Hello, Azure Blob Storage!
Enter fullscreen mode Exit fullscreen mode

Descargar un blob:

GET https://{account}.blob.core.windows.net/{container}/{blob}
Authorization: Bearer {token}
x-ms-version: 2023-01-03
Enter fullscreen mode Exit fullscreen mode

Pruebas con Apidog

Las API de Azure Storage requieren encabezados específicos (x-ms-version, autorización). Con Apidog puede:

  1. Guardar solicitudes reutilizables
  2. Usar variables de entorno para cuentas y tokens
  3. Validar respuestas según esquemas esperados

Diseñe y pruebe las API de Azure Storage de forma eficiente.

API de Azure Compute

Azure Compute permite administrar máquinas virtuales, contenedores y funciones serverless.

API de Azure Functions

Listar funciones en una app de funciones:

GET https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Web/sites/{app-name}/functions?api-version=2023-01-01
Authorization: Bearer {management-token}
Enter fullscreen mode Exit fullscreen mode

Activar una función (HTTP trigger):

POST https://{app-name}.azurewebsites.net/api/{function-name}
Content-Type: application/json

{
  "name": "Azure",
  "message": "Hello from API"
}
Enter fullscreen mode Exit fullscreen mode

Obtener claves de función:

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Web/sites/{app-name}/functions/{function-name}/listKeys?api-version=2023-01-01
Authorization: Bearer {management-token}
Enter fullscreen mode Exit fullscreen mode

API de Máquinas Virtuales

Listar VM:

GET https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/virtualMachines?api-version=2023-07-01
Authorization: Bearer {management-token}
Enter fullscreen mode Exit fullscreen mode

Iniciar una VM:

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Compute/virtualMachines/{vm-name}/start?api-version=2023-07-01
Authorization: Bearer {management-token}
Enter fullscreen mode Exit fullscreen mode

Detener una VM:

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{rg}/providers/Microsoft.Compute/virtualMachines/{vm-name}/powerOff?api-version=2023-07-01
Authorization: Bearer {management-token}
Enter fullscreen mode Exit fullscreen mode

API de Servicios de IA de Azure

Azure ofrece modelos OpenAI y servicios cognitivos (visión, voz, lenguaje).

API de Azure OpenAI

Obtener completaciones:

POST https://{resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version=2024-02-15-preview
api-key: {your-api-key}
Content-Type: application/json

{
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Azure?"}
  ],
  "max_tokens": 500
}
Enter fullscreen mode Exit fullscreen mode

Listar implementaciones:

GET https://{resource-name}.openai.azure.com/openai/deployments?api-version=2024-02-15-preview
api-key: {your-api-key}
Enter fullscreen mode Exit fullscreen mode

API de Servicios Cognitivos

Text Analytics - Sentimiento:

POST https://{resource-name}.cognitiveservices.azure.com/text/analytics/v3.1/sentiment
Ocp-Apim-Subscription-Key: {subscription-key}
Content-Type: application/json

{
  "documents": [
    {
      "id": "1",
      "language": "en",
      "text": "I love Azure APIs. They work great!"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Computer Vision - Analizar imagen:

POST https://{resource-name}.cognitiveservices.azure.com/vision/v3.2/analyze?visualFeatures=Description,Tags
Ocp-Apim-Subscription-Key: {subscription-key}
Content-Type: application/octet-stream

[binary image data]
Enter fullscreen mode Exit fullscreen mode

Pruebas de API de Azure con Apidog

Las API de Azure tienen autenticación compleja y requieren encabezados precisos. Probarlas manualmente con curl es propenso a errores. Con Apidog puede automatizar:

1. Gestión de entornos

Las API de Azure involucran múltiples endpoints:

  • management.azure.com para administración
  • {account}.blob.core.windows.net para almacenamiento
  • {resource}.openai.azure.com para IA

Cree entornos en Apidog para cada uno:

# Desarrollo
MANAGEMENT_TOKEN: eyJ0eXAiOiJKV1Qi...
STORAGE_ACCOUNT: devstorage
OPENAI_RESOURCE: dev-openai

# Producción
MANAGEMENT_TOKEN: eyJ0eXAiOiJKV1Qi...
STORAGE_ACCOUNT: prodstorage
OPENAI_RESOURCE: prod-openai
Enter fullscreen mode Exit fullscreen mode

2. Scripts de pre-solicitud para actualización de tokens

Los tokens expiran tras una hora. Use un script de pre-solicitud:

// Comprobar si el token ha caducado
const tokenExpiry = pm.environment.get('token_expiry')
const now = Date.now() / 1000

if (!tokenExpiry || now >= tokenExpiry) {
  // Solicitar nuevo token
  const response = await pm.sendRequest({
    url: 'https://login.microsoftonline.com/' + pm.environment.get('tenant_id') + '/oauth2/v2.0/token',
    method: 'POST',
    header: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: {
      mode: 'urlencoded',
      urlencoded: [
        { key: 'client_id', value: pm.environment.get('client_id') },
        { key: 'client_secret', value: pm.environment.get('client_secret') },
        { key: 'scope', value: 'https://management.azure.com/.default' },
        { key: 'grant_type', value: 'client_credentials' }
      ]
    }
  })

  const data = response.json()
  pm.environment.set('management_token', data.access_token)
  pm.environment.set('token_expiry', now + data.expires_in)
}
Enter fullscreen mode Exit fullscreen mode

3. Validación de respuesta

Valide que la respuesta de Azure tenga la estructura esperada:

// Validar que la lista de blobs devuelve la estructura esperada
pm.test('La respuesta tiene contenedores', () => {
  const xml = pm.response.text()
  pm.expect(xml).to.include('<Containers>')
  pm.expect(xml).to.include('<Container>')
})

pm.test('La respuesta es XML válido', () => {
  pm.response.to.be.ok
  pm.response.to.have.header('Content-Type', 'application/xml')
})
Enter fullscreen mode Exit fullscreen mode

Errores comunes y cómo solucionarlos

401 No autorizado

Causa: Token inválido o caducado.

Solución:

  1. Verifique que el token no haya expirado (expires_in suele ser 3600)
  2. Verifique que el scope coincida con la API llamada
  3. Asegúrese de que la app tenga permisos correctos

403 Prohibido

Causa: Token válido pero sin permisos suficientes.

Solución:

  1. Vaya al recurso en Azure Portal
  2. Verifique el control de acceso (IAM)
  3. Asigne el rol correcto al principal de servicio de su app

404 No encontrado

Causa: Endpoint incorrecto o recurso inexistente.

Solución:

  1. Revise el nombre de recurso en la URL
  2. Verifique la versión de la API en la querystring
  3. Confirme que el recurso existe en el grupo adecuado

429 Demasiadas solicitudes

Causa: Se alcanzó el límite de tasa de Azure.

Solución:

  1. Implemente retroceso exponencial
  2. Verifique el header x-ms-ratelimit-remaining
  3. Considere agrupar llamadas 
async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (error.statusCode === 429) {
        const delay = Math.pow(2, i) * 1000
        await new Promise(resolve => setTimeout(resolve, delay))
      } else {
        throw error
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Alternativas y comparaciones

Característica API de Azure API de AWS API de GCP
Autenticación Azure AD (OAuth 2.0) IAM (Sig v4) OAuth 2.0
Calidad del SDK Excelente Excelente Excelente
Documentación Completa pero dispersa Específica del servicio Específica del servicio
Límite de tasa Por suscripción Por servicio Por proyecto
Nivel gratuito 12 meses + siempre gratis 12 meses Siempre gratis + créditos

La autenticación de Azure es más compleja que la de AWS (firmas), pero se integra mejor con sistemas de identidad corporativos.

Casos de uso del mundo real

Plataforma e-commerce: Alternativa a Shopify que utiliza Azure Blob Storage para imágenes, Azure Functions para webhooks y Azure OpenAI para descripciones de producto. Todas las llamadas a la API se prueban en Apidog antes del despliegue.

SaaS de salud: Sistema de registros médicos con Cosmos DB para datos, Functions para procesamiento HL7 y Key Vault para secretos. Las pruebas de API garantizan cumplimiento HIPAA validando cada respuesta.

Startup de IA: Usa Azure OpenAI para LLM, Storage para datos de entrenamiento y Container Apps para despliegue. Simulan las API de Azure en Apidog para desarrollo local.

Conclusión

Resumen práctico:

  • Azure utiliza tokens OAuth 2.0 de Azure AD (Entra ID)
  • Las API de Storage requieren el header x-ms-version y tokens Bearer válidos
  • Las API de Compute usan el endpoint de Azure Resource Manager
  • Los servicios de IA usan claves de API o tokens AAD según el caso
  • Pruebe y documente sus integraciones de Azure con Apidog

Próximos pasos:

  1. Registre una app en Azure AD y obtenga credenciales
  2. Solicite un token de acceso con el flujo de credenciales de cliente
  3. Realice su primera llamada a la API de Azure Storage
  4. Guarde la solicitud en Apidog como reutilizable
  5. Cree una colección para las API de su proyecto

Pruebe las API de Azure con Apidog, gratis.

Preguntas frecuentes

¿Cuál es la diferencia entre Azure AD y Microsoft Entra ID?

Son lo mismo. Microsoft renombró Azure Active Directory a Microsoft Entra ID en 2023. Use Entra ID en nueva documentación, pero Azure AD sigue apareciendo en ejemplos.

¿Cómo obtengo una clave de API para Azure OpenAI?

En Azure Portal → Azure OpenAI → su recurso → Claves y Endpoint. Verá dos claves; ambas funcionan. Regenerelas periódicamente. Azure OpenAI requiere suscripción y despliegue de recurso.

¿Cuál es la diferencia entre management.azure.com y endpoints de servicio?

management.azure.com es para operaciones CRUD de recursos (crear VM, eliminar cuenta). Los endpoints específicos ({account}.blob.core.windows.net, {resource}.openai.azure.com) son para usar recursos (subir archivos, generar texto). Necesita tokens diferentes para cada uno.

¿Cuánto duran los tokens de acceso de Azure?

Normalmente 1 hora (3600 segundos). Solicite un nuevo token antes de que caduque. Use el campo expires_in para programar renovaciones. No solicite un token en cada llamada.

¿Puedo usar identidades administradas en vez de secretos de cliente?

Sí, y es recomendable para cargas de producción en Azure. Las identidades administradas eliminan la gestión de secretos. Funciona con VMs, Functions, Container Apps y AKS. Para desarrollo local use Azure CLI (az login) o variables de entorno.

¿Por qué mi llamada funciona en Postman pero falla en código?

Revise los encabezados. Azure distingue mayúsculas/minúsculas. Postman puede agregar headers automáticamente. Compare la solicitud bruta con su código usando Fiddler o la inspección de Apidog.

¿Cómo pruebo las API de Azure localmente sin suscripción?

No es posible probar todo sin suscripción, pero puede usar emuladores:

  • Azurite para Storage
  • Azure Functions Core Tools para Functions
  • Use Apidog para simular respuestas

¿Cómo gestiono errores de API de Azure?

Azure devuelve errores detallados en JSON. Analice los campos error.code y error.message. Códigos comunes:

  • AuthenticationFailed: revise su token
  • ResourceNotFound: revise el nombre del recurso
  • OperationNotAllowed: revise los límites de su suscripción

Top comments (0)