Referencia de la API REST de Azure

Le damos la bienvenida a la documentación de referencia de la API REST de Azure.

Las API de transferencia de estado representacional (REST) son puntos de conexión de servicio que admiten una serie de operaciones HTTP (métodos), que proporcionan acceso de creación, recuperación, actualización o eliminación del acceso a los recursos del servicio. Este artículo le enseñará a:

• Cómo llamar a las API REST de Azure con curl
• Los componentes básicos de un par de solicitud/respuesta de la API rest.
• Cómo registrar la aplicación cliente con Microsoft Entra ID para proteger las solicitudes REST.
• Información general sobre cómo crear y enviar una solicitud REST y controlar la respuesta.

Cómo llamar a las API REST de Azure con curl

El proceso descrito en la siguiente entrada de blog muestra cómo llamar a una API REST de Azure mediante curl. Es posible que considere la posibilidad de usar curl en scripts desatendidos. Por ejemplo, en escenarios de automatización de DevOps.

Llamada a la API REST de Azure mediante curl

Componentes de una solicitud/respuesta de la API de REST

Un par de solicitud/respuesta de una API de REST puede dividirse en cinco componentes:

1. El URI de la solicitud, que consta de: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Aunque el URI de solicitud se incluye en el encabezado del mensaje de solicitud, aquí lo mencionamos por separado porque la mayoría de los lenguajes o marcos de trabajo le exigen que lo pase por separado desde el mensaje de solicitud.

   • Esquema de URI: indica el protocolo usado para transmitir la solicitud. Por ejemplo, http o https.
   • Host de URI: especifica el nombre de dominio o la dirección IP del servidor donde se hospeda el punto de conexión de servicio REST, como graph.microsoft.com.
   • Ruta de acceso del recurso: especifica el recurso o una colección de recursos, que puede incluir varios segmentos usados por el servicio a la hora de determinar la selección de esos recursos. Por ejemplo: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners puede usarse para consultar en la lista los propietarios de una aplicación específica dentro de la colección de aplicaciones.
   • (Opcional) Cadena de consulta: proporciona más parámetros simples, como los criterios de selección de recursos o la versión de la API.

2. Campos de encabezado del mensaje de solicitud HTTP:

   • Un método HTTP necesario (también conocido como operación o verbo), que indica al servicio qué tipo de operación solicita. Las API REST de Azure admiten métodos GET, HEAD, PUT, POST y PATCH.
   • Campos de encabezado adicionales y opcionales, según necesite el método HTTP y el URI especificados. Por ejemplo, un encabezado Authorization que proporciona un token de portador que contiene información de autorización de cliente para la solicitud.

3. Campos de cuerpo de mensaje de solicitudes HTTP opcionales para admitir la operación HTTP y el URI. Por ejemplo, las operaciones POST contienen objetos codificados con MIME que se pasan como parámetros complejos. Para las operaciones POST o PUT, el tipo de codificación MIME para el cuerpo también debe especificarse en el encabezado de solicitud Content-type. Algunos servicios requieren que se use un tipo MIME concreto, como application/json.

4. Campos de encabezado de mensaje de respuesta HTTP:

   • Un código de estado HTTP, que puede ser 2xx para los códigos correctos y 4xx o 5xx para los códigos de error. Como alternativa se puede devolver un código de estado definido por el servicio, como se indica en la documentación de la API.
   • Campos de encabezado adicionales y opcionales, según sea necesario para admitir la respuesta a la solicitud, como un encabezado de respuesta Content-type.

5. Campos de cuerpo del mensaje de respuesta HTTP opcionales:

   • Se devuelven objetos de respuesta codificados con MIME en el cuerpo de respuesta HTTP, como una respuesta de un método GET que devuelve datos. Normalmente, estos objetos se devuelven en un formato estructurado como JSON o XML, tal y como se indica en el encabezado de respuesta Content-type. Por ejemplo, cuando se solicita un token de acceso de Microsoft Entra ID, se devuelve en el cuerpo de la respuesta como elemento access_token , uno de varios objetos emparejados de nombre y valor en una colección de datos. En este ejemplo, también se incluye un encabezado de respuesta de Content-Type: application/json .

Registro de la aplicación cliente con Microsoft Entra ID

La mayoría de los servicios de Azure (como los proveedores de Azure Resource Manager y el modelo de implementación clásica) requieren que el código de cliente se autentique con credenciales válidas para poder llamar a la API del servicio. La autenticación se coordina entre los distintos actores mediante Microsoft Entra ID y proporciona al cliente un token de acceso como prueba de la autenticación. A continuación, el token se envía al servicio de Azure en el encabezado de autorización HTTP de las solicitudes de API REST posteriores. Las notificaciones del token también proporcionan información al servicio, lo que le permite validar el cliente y realizar cualquier autorización necesaria.

Si usa una API REST que no usa la autenticación integrada Microsoft Entra o ya ha registrado el cliente, vaya a la sección Crear la solicitud.

Requisitos previos

La aplicación cliente debe hacer que su configuración de identidad sea conocida para Microsoft Entra ID antes del tiempo de ejecución registrándolo en un inquilino de Microsoft Entra. Antes de registrar el cliente con Microsoft Entra ID, tenga en cuenta los siguientes requisitos previos:

• Si aún no tiene un inquilino de Microsoft Entra, consulte Configuración de un inquilino de Microsoft Entra.

• De acuerdo con el marco de autorización de OAuth2, Microsoft Entra ID admite dos tipos de clientes. Comprender cada uno le ayuda a decidir cuál es el más adecuado para su escenario:

  • Los clientes web o confidenciales se ejecutan en un servidor web y pueden acceder a los recursos bajo su propia identidad (por ejemplo, un servicio o demonio) o obtener autorización delegada para acceder a los recursos bajo la identidad de un usuario que ha iniciado sesión (por ejemplo, una aplicación web). Solo un cliente web puede mantener y presentar sus propias credenciales durante Microsoft Entra autenticación para adquirir un token de acceso.
  • Los clientes nativos o públicos se instalan y ejecutan en un dispositivo. Solo pueden acceder a los recursos bajo autorización delegada, mediante la identidad del usuario que ha iniciado sesión para adquirir un token de acceso en nombre del usuario.

• El proceso de registro crea dos objetos relacionados en el inquilino de Microsoft Entra donde se registra la aplicación: un objeto de aplicación y un objeto de entidad de servicio. Para obtener más información sobre estos componentes y cómo se usan en tiempo de ejecución, consulte Objetos de aplicación y entidad de servicio en Microsoft Entra ID.

Ya está listo para registrar la aplicación cliente con Microsoft Entra ID.

Registro de cliente

Para registrar un cliente que acceda a una API rest de Azure Resource Manager, consulte Uso del portal para crear Microsoft Entra aplicación y entidad de servicio que puedan acceder a los recursos. En el artículo (también disponible en PowerShell y las versiones de la CLI para automatizar el registro), se muestra cómo:

• Registre la aplicación cliente con Microsoft Entra ID.
• Establezca solicitudes de permisos para permitir que el cliente acceda a la API de Azure Resource Manager.
• Configure los valores de Azure Resource Manager Role-Based Access Control (RBAC) para autorizar el cliente.

Si el cliente accede a una API distinta de una API de Azure Resource Manager, consulte:

• Registro de una aplicación con la plataforma de identidad de Microsoft
  • Registre la aplicación cliente con Microsoft Entra ID, en la sección "Registrar una aplicación".
  • Cree una clave secreta (si va a registrar un cliente web), en la sección "Agregar credenciales".
• Configuración de una aplicación para exponer una API web
  • Agregar permisos a la API web y exponerlos como ámbitos
• Configuración de una aplicación cliente para acceder a una API web
  • Agregue solicitudes de permisos según sea necesario en los ámbitos definidos para la API, en la sección "Agregar permisos para acceder a la API web".

Ahora que ha completado el registro de la aplicación cliente, vaya al código de cliente donde cree la solicitud REST y controle la respuesta.

Creación de la solicitud

En esta sección se tratan los tres primeros componentes que se han descrito anteriormente. Primero debe adquirir el token de acceso de Microsoft Entra ID, que se usa para ensamblar el encabezado del mensaje de solicitud.

Adquisición de un token de acceso

Después de tener un registro de cliente válido, tiene dos maneras de integrarse con Microsoft Entra ID para adquirir un token de acceso:

• Puntos de conexión de servicio OAuth2 independientes del lenguaje y de la plataforma, que se usan en este artículo. Las instrucciones proporcionadas en esta sección no asumen nada sobre la plataforma o el lenguaje o script del cliente cuando se usan los puntos de conexión de OAuth de Microsoft Entra. El único requisito es que puede enviar o recibir solicitudes HTTPS hacia y desde Microsoft Entra ID y analizar el mensaje de respuesta.
• Las bibliotecas de autenticación de Microsoft (MSAL) específicas de la plataforma y del idioma, que están fuera del ámbito de este artículo. Las bibliotecas proporcionan contenedores asincrónicos para las solicitudes de punto de conexión de OAuth2 y características sólidas de control de tokens, como el almacenamiento en caché y la administración de tokens de actualización. Para obtener más información, consulte La información general de la Biblioteca de autenticación de Microsoft (MSAL).

Los dos puntos de conexión Microsoft Entra que se usan para autenticar el cliente y adquirir un token de acceso se conocen como OAuth2 /authorize y /token puntos de conexión. La forma en que las usa depende del registro de la aplicación y del tipo de flujo de concesión de autorización de OAuth2 que necesita para admitir la aplicación en tiempo de ejecución. Para los fines de este artículo, se supone que el cliente usa uno de los siguientes flujos de concesión de autorización: código de autorización o credenciales de cliente. Para adquirir un token de acceso usado en las secciones restantes, siga las instrucciones del flujo que mejor se adapte a su escenario.

Concesión de código de autorización (clientes interactivos)

Esta concesión la usan los clientes web y nativos, lo que requiere credenciales de un usuario que ha iniciado sesión para delegar el acceso de recursos a la aplicación cliente. Usa el /authorize punto de conexión para obtener un código de autorización (en respuesta al inicio de sesión o consentimiento del usuario), seguido del /token punto de conexión para intercambiar el código de autorización de un token de acceso.

1. En primer lugar, el cliente debe solicitar un código de autorización de Microsoft Entra ID. Para obtener más información sobre el formato de la solicitud HTTPS GET al /authorize punto de conexión y los mensajes de solicitud y respuesta de ejemplo, consulte Solicitud de un código de autorización. El URI contiene los siguientes parámetros de cadena de consulta, que son específicos de la aplicación cliente:

   • client_id: GUID que se asignó a la aplicación cliente durante el registro, también conocido como identificador de aplicación.

   • redirect_uri: una versión con codificación URL de uno de los URI de respuesta y redireccionamiento, especificado durante el registro de la aplicación cliente. El valor que pase debe coincidir exactamente con el valor de registro.

   • resource: un URI de identificador con codificación URL especificado por la API REST que llama. Las API web o REST (también conocidas como aplicaciones de recursos) pueden exponer uno o varios URI de identificador de aplicación en su configuración. Por ejemplo:

     • Las API del proveedor de Azure Resource Manager (y el modelo de implementación clásica) usan https://management.core.windows.net/.
     • Para cualquier otro recurso, consulte la documentación de la API o la configuración de la aplicación de recursos en el Azure Portal. Para obtener más información, vea la identifierUris propiedad del objeto de aplicación de Microsoft Graph API.

   La solicitud al /authorize punto de conexión desencadena primero un aviso de inicio de sesión para autenticar al usuario. La respuesta que se devuelve se entrega como redireccionamiento (302) al URI que especificó en redirect_uri. El mensaje de encabezado de respuesta contiene un location campo, que contiene el URI de redirección seguido de un code parámetro de consulta. El code parámetro contiene el código de autorización que necesita para el paso 2.

2. A continuación, el cliente debe canjear el código de autorización por un token de acceso. Para más información sobre el formato de la solicitud HTTPS POST al /token punto de conexión y ejemplos de solicitud/respuesta, consulte Solicitud de un token de acceso. Dado que se trata de una solicitud POST, empaqueta los parámetros específicos de la aplicación en el cuerpo de la solicitud. Además de algunos de los parámetros mencionados anteriormente (junto con otros nuevos), pasará lo siguiente:

   • code: este parámetro de consulta contiene el código de autorización que obtuvo en el paso 1.

   • client_secret: solo necesita este parámetro si el cliente está configurado como una aplicación web. Este es el mismo valor de clave y secreto que generó anteriormente, en el registro de cliente.

Concesión de credenciales de cliente (clientes no interactivos)

Esta concesión solo la usan los clientes web, lo que permite que la aplicación acceda directamente a los recursos (sin delegación de usuarios) mediante las credenciales del cliente, que se proporcionan en el momento del registro. Normalmente, los clientes no interactivos (sin interfaz de usuario) que se ejecutan como un servicio o demonio usan la concesión. Solo requiere que el /token punto de conexión adquiera un token de acceso.

Las interacciones de cliente/recurso para esta concesión son similares al paso 2 de la concesión de código de autorización. Para obtener más información sobre el formato de la solicitud HTTPS POST al /token punto de conexión y ejemplos de solicitud y respuesta, consulte la sección "Obtener un token" en Plataforma de identidad de Microsoft y el flujo de credenciales de cliente de OAuth 2.0.

Ensamblado del mensaje de solicitud

La mayoría de los lenguajes de programación o marcos y entornos de scripting facilitan el montaje y envío del mensaje de solicitud. Normalmente proporcionan una api o clase web/HTTP que abstrae la creación o el formato de la solicitud, lo que facilita la escritura del código de cliente (la HttpWebRequest clase en .NET Framework, por ejemplo). Por motivos de brevedad, y como la mayoría de la tarea se controla automáticamente, en esta sección solo se tratan los elementos importantes de la solicitud.

URI de solicitud

Dado que se transmite y recibe información confidencial, todas las solicitudes REST requieren el protocolo HTTPS para el esquema de URI, lo que proporciona a la solicitud y respuesta un canal seguro. La información (es decir, el código de autorización Microsoft Entra, el token de acceso/portador y los datos confidenciales de solicitud/respuesta) se cifra mediante una capa de transporte inferior, lo que garantiza la privacidad de los mensajes.

El resto del URI de solicitud del servicio (el host, la ruta de acceso del recurso y los parámetros de cadena de consulta necesarios) se determinan mediante su especificación de API REST relacionada. Por ejemplo, las API del proveedor de Azure Resource Manager usan https://management.azure.com/y el modelo de implementación clásica de Azure usa https://management.core.windows.net/. Ambos requieren un api-version parámetro de cadena de consulta.

Encabezado de solicitud

El URI de solicitud se agrupa en el encabezado del mensaje de solicitud, junto con los campos adicionales requeridos por la especificación de la API REST del servicio y la especificación HTTP. La solicitud puede requerir los siguientes campos de encabezado comunes:

• Authorization: contiene el token de portador de OAuth2 para proteger la solicitud, como se adquirió anteriormente de Microsoft Entra ID.
• Content-Type: normalmente se establece en "application/json" (pares nombre-valor en formato JSON) y especifica el tipo MIME del cuerpo de la solicitud.
• Host: el nombre de dominio o la dirección IP del servidor donde se hospeda el punto de conexión del servicio REST.

Cuerpo de la solicitud

Como se mencionó anteriormente, el cuerpo del mensaje de solicitud es opcional, según la operación específica que solicite y sus requisitos de parámetro. Si es necesario, la especificación de API para el servicio que solicita también especifica la codificación y el formato.

El cuerpo de la solicitud está separado del encabezado por una línea vacía, con formato de acuerdo con el Content-Type campo de encabezado. Un ejemplo de un cuerpo con formato "application/json" aparecería de la siguiente manera:

{
  "<name>": "<value>"
}

Envío de la solicitud

Ahora que tiene el URI de solicitud del servicio y ha creado el encabezado y el cuerpo del mensaje de solicitud relacionados, está listo para enviar la solicitud al punto de conexión del servicio REST.

Por ejemplo, puede enviar un método de solicitud HTTPS GET para un proveedor de Azure Resource Manager mediante campos de encabezado de solicitud similares a los siguientes (tenga en cuenta que el cuerpo de la solicitud está vacío):

GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com

<no body>

Y puede enviar un método de solicitud HTTPS PUT para un proveedor de Azure Resource Manager, mediante el uso de campos de encabezado de solicitud y cuerpo similares al ejemplo siguiente:

PUT /subscriptions/.../resourcegroups/ExampleResourceGroup?api-version=2016-02-01  HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com

{
  "location": "West US"
}

Después de realizar la solicitud, se devuelven el encabezado del mensaje de respuesta y el cuerpo opcional.

Procesamiento del mensaje de respuesta

El proceso concluye con los dos últimos componentes.

Para procesar la respuesta, analice el encabezado de respuesta y, opcionalmente, el cuerpo de la respuesta (según la solicitud). En el ejemplo HTTPS GET proporcionado en la sección anterior, usó el punto de conexión /subscriptions para recuperar la lista de suscripciones de un usuario. Suponiendo que la respuesta se realizó correctamente, debe recibir campos de encabezado de respuesta similares al ejemplo siguiente:

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

Y debe recibir un cuerpo de respuesta que contenga una lista de suscripciones de Azure y sus propiedades individuales codificadas en formato JSON, de forma similar a:

{
    "value":[
        {
        "id":"/subscriptions/...",
        "subscriptionId":"...",
        "displayName":"My Azure Subscription",
        "state":"Enabled",

"subscriptionPolicies":{
            "locationPlacementId":"Public_2015-09-01",
            "quotaId":"MSDN_2014-05-01",
            "spendingLimit":"On"}
        }
    ]
}

Del mismo modo, para el ejemplo HTTPS PUT, debe recibir un encabezado de respuesta similar al siguiente, confirmando que la operación PUT para agregar "ExampleResourceGroup" se realizó correctamente:

HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;

Y debería recibir un cuerpo de respuesta que confirme el contenido del grupo de recursos recién agregado codificado en formato JSON, similar a:

{
    "id":"/subscriptions/.../resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

Al igual que con la solicitud, la mayoría de los lenguajes de programación y marcos facilitan el procesamiento del mensaje de respuesta. Normalmente, devuelven esta información a la aplicación después de la solicitud, lo que le permite procesarla en un formato con tipo o estructurado. Principalmente, le interesa confirmar el código de estado HTTP en el encabezado de respuesta y analizar el cuerpo de la respuesta según la especificación de la API (o los Content-Type campos de encabezado de respuesta y Content-Length ).

Operaciones asincrónicas, limitación y paginación

El patrón Create/Send/Process-Response descrito en este artículo es sincrónico y se aplica a todos los mensajes REST. Sin embargo, algunos servicios también admiten un patrón asincrónico, que requiere un procesamiento adicional de encabezados de respuesta para supervisar o completar la solicitud asincrónica. Para obtener más información, consulte Seguimiento de las operaciones asincrónicas de Azure.

Resource Manager aplica un límite en el número de solicitudes de lectura y escritura por hora para evitar que una aplicación envíe demasiadas solicitudes. Si la aplicación supera esos límites, se limitan las solicitudes. El encabezado de respuesta incluye el número de solicitudes restantes para el ámbito. Para más información, consulte Limitación de solicitudes de Resource Manager.

Algunas operaciones de lista devuelven una propiedad denominada nextLink en el cuerpo de la respuesta. Verá esta propiedad cuando los resultados son demasiado grandes para devolver en una respuesta. Normalmente, la respuesta incluye la propiedad nextLink cuando la operación de lista devuelve más de 1000 elementos. Cuando nextLink no está presente en los resultados, se completan los resultados devueltos. Cuando nextLink contiene una dirección URL, los resultados devueltos forman parte del conjunto de resultados total.

La respuesta tiene el formato :

{
  "value": [
    <returned-items>
  ],
  "nextLink": "https://management.azure.com/{operation}?api-version={version}&%24skiptoken={token}"
}

Para obtener la siguiente página de los resultados, envíe una solicitud GET a la dirección URL en la propiedad nextLink. La dirección URL incluye un token de continuación para indicar dónde se encuentran los resultados. Continúe enviando solicitudes a la dirección URL de nextLink hasta que ya no contenga una dirección URL en los resultados devueltos.

Resistencia de las API de Azure

Las API REST de Azure están diseñadas para lograr resistencia y disponibilidad continua. Las operaciones del plano de control (solicitudes enviadas a management.azure.com) en la API REST son:

• Se distribuyen entre regiones. Algunos servicios son regionales.

• Se distribuyen entre las zonas de disponibilidad (así como regiones) en aquellas ubicaciones que tienen varias zonas de disponibilidad.

• No dependen de un solo centro de datos lógicos.

• Nunca se interrumpen debido a actividades de mantenimiento.

Contenido relacionado

Eso es todo. Después de registrar la aplicación Microsoft Entra y de tener una técnica modular para adquirir un token de acceso y controlar las solicitudes HTTP, es bastante fácil replicar el código para aprovechar las nuevas API rest. Para obtener más información sobre el registro de aplicaciones y el modelo de programación de Microsoft Entra, consulte la documentación de Plataforma de identidad de Microsoft.

Para obtener información sobre cómo probar solicitudes/respuestas HTTP, consulte:

• Fiddler. Fiddler es un proxy de depuración web gratuito que puede interceptar las solicitudes REST, lo que facilita el diagnóstico de los mensajes de solicitud/respuesta HTTP.
• JWT.ms, lo que hace que sea rápido y fácil volcar las notificaciones en el token de portador para que pueda validar su contenido.