Azure REST API Reference (Referencia de API de REST en Azure)

  • Artículo

Le damos la bienvenida a la referencia de la API REST de Azure.

Las API de transferencia de estado representacional (REST) son puntos de conexión de servicio que admiten conjuntos de operaciones HTTP (métodos), que proporcionan acceso de creación, recuperación, actualización y eliminación a los recursos del servicio. Las secciones siguientes le guiarán por:

  • Los componentes básicos de un par de solicitud/respuesta de la API REST
  • Registro de la aplicación cliente con Azure Active Directory (Azure AD) para proteger las solicitudes REST
  • Información general sobre cómo crear y enviar una solicitud REST y controlar la respuesta

Nota:

La mayoría de las API REST del servicio de Azure tienen una biblioteca de SDK de cliente correspondiente, que controla gran parte del código de cliente. Vea:

Azure SDK para .NET
SDK de Java de Azure
Azure CLI 2.0 SDK

Componentes de una solicitud/respuesta de la API de REST

Un par de solicitud/respuesta de la API REST se puede separar en 5 componentes:

  1. El URI de la solicitud, que consta de: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Tenga en cuenta que estamos llamando a esto por separado aquí, ya que la mayoría de los lenguajes o marcos requieren que pase esto por separado del mensaje de solicitud, pero realmente se incluye en el encabezado del mensaje de solicitud.
    • Esquema de URI: indica el protocolo utilizado para transmitir la solicitud. Por ejemplo, http o https.
    • Host de URI: el nombre de dominio o la dirección IP del servidor donde se hospeda el punto de conexión del servicio REST, como graph.microsoft.com
    • Ruta de acceso del recurso: especifica el recurso o la colección de recursos, que puede incluir varios segmentos usados por el servicio para determinar la selección de esos recursos. Por ejemplo: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners se podría usar para consultar la lista de propietarios de una aplicación específica dentro de la colección de aplicaciones.
    • Cadena de consulta (opcional): se usa para proporcionar parámetros simples adicionales, como la versión de la API, los criterios de selección de recursos, etc.
  2. Campos de encabezado de 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 opcionales según sea necesario para el URI y el método HTTP 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 pasados como parámetros complejos. El tipo de codificación MIME para el cuerpo debe especificarse también en el Content-type encabezado de solicitud para las operaciones POST/PUT. Tenga en cuenta que algunos servicios requieren que use un tipo MIME específico, como application/json.
  4. Campos de encabezado del mensaje de respuesta HTTP
    • Código de estado HTTP, que va desde códigos de éxito 2xx hasta códigos de error 4xx/5xx. 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 opcionales según sea necesario para admitir la respuesta de la solicitud, como un Content-type encabezado de respuesta.
  5. Campos opcionales del cuerpo del mensaje de respuesta HTTP
    • Los objetos de respuesta codificados en MIME se pueden devolver en el cuerpo de la respuesta HTTP, como una respuesta de un método GET que devuelve datos. Normalmente, estos se devolverán en un formato estructurado como JSON o XML, como se indica en el encabezado de Content-type respuesta. Por ejemplo, al solicitar un token de acceso desde Azure AD, se devolverá en el cuerpo de la respuesta como el access_token elemento , uno de varios objetos emparejados de nombre y valor en una colección de datos. En este ejemplo, también se incluirá un encabezado de respuesta de Content-Type: application/json .

Registro de la aplicación cliente con Azure AD

La mayoría de los servicios de Azure (como los proveedores de Azure Resource Manager y las API clásicas de Service Management) requieren que el código de cliente se autentique con credenciales válidas antes de poder llamar a la API del servicio. Azure AD coordina la autenticación entre los distintos actores, que proporciona al cliente un token de acceso como prueba de la autenticación o autorización. A continuación, el token se envía al servicio de Azure en el encabezado de autorización HTTP de todas 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 de Azure AD o ya ha registrado el cliente, puede ir directamente a la sección Creación de la solicitud .

Requisitos previos

La aplicación cliente debe hacer que se conozca la configuración de identidad de Azure AD antes del tiempo de ejecución, registrándolo en un inquilino de Azure AD. A continuación se muestra una lista de elementos que se deben tener en cuenta antes de registrar el cliente con Azure AD:

  • Si aún no tiene un inquilino de Azure AD, consulte Obtención de un inquilino de Azure Active Directory.
  • Según el marco de autorización de OAuth2, Azure AD admite dos tipos de clientes. Comprender cada uno le ayudará a decidir cuál es el más adecuado para su escenario:
    • Los clientes web/confidenciales (se ejecutan en un servidor web) pueden acceder a los recursos en su propia identidad (es decir, servicio o demonio) o obtener autorización delegada para acceder a los recursos bajo la identidad del usuario que ha iniciado sesión (es decir, aplicación web). Solo un cliente web tiene la capacidad de mantener y presentar de forma segura sus propias credenciales durante la autenticación de Azure AD para adquirir un token de acceso.
    • Los clientes nativos o públicos (instalados o ejecutados 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 creará 2 objetos relacionados en el inquilino de Azure AD 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 Azure Active Directory.

Ahora estamos listos para registrar la aplicación cliente con Azure AD.

Registro de cliente

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

  • registro de la aplicación cliente con Azure AD
  • establecer solicitudes de permisos para permitir que el cliente acceda a la API de Azure Resource Manager
  • configuración de la Access Control basada en roles (RBAC) de Azure Resource Manager para autorizar el cliente

Para todos los demás clientes, consulte Integración de aplicaciones con Azure Active Directory. Este artículo le mostrará cómo realizar los siguientes procedimientos:

  • registrar la aplicación cliente con Azure AD, en la sección "Agregar una aplicación"
  • crear una clave secreta (si va a registrar un cliente web), en la sección "Actualización de una aplicación"
  • agregue solicitudes de permisos según sea necesario para la API, en la sección "Actualización de una aplicación".

Ahora que ha completado el registro de la aplicación cliente, podemos pasar al código de cliente, donde creará la solicitud REST y controlará la respuesta.

Creación de la solicitud

En esta sección se tratan los primeros 3 de los cinco componentes que hemos analizado anteriormente. En primer lugar, es necesario adquirir el token de acceso de Azure AD, que usaremos para ensamblar el encabezado del mensaje de solicitud.

Adquisición de un token de acceso

Una vez que tenga un registro de cliente válido, básicamente hay dos maneras de integrar con Azure AD para adquirir un token de acceso:

  • Los puntos de conexión de servicio de OAuth2 independiente del lenguaje o plataforma de Azure AD, que es lo que usaremos. Al igual que los puntos de conexión de la API REST de Azure que está usando, las instrucciones proporcionadas en esta sección no asumen ninguna suposición sobre la plataforma o script del cliente al usar los puntos de conexión de Azure AD; solo que puede enviar o recibir solicitudes HTTPS a Azure AD y analizar el mensaje de respuesta.
  • Las bibliotecas de autenticación de Microsoft (MSAL) específicas del lenguaje o la plataforma. 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, incluida la documentación de referencia, las descargas de biblioteca y el código de ejemplo, consulte Bibliotecas de autenticación de Microsoft.

Los 2 puntos de conexión de Azure AD que va a usar para autenticar al cliente y adquirir un token de acceso se conocen como puntos de conexión y /token OAuth2/authorize. La forma de usarlos dependerá del registro de la aplicación y del tipo de flujo de concesión de autorización de OAuth2 que necesite para admitir la aplicación en tiempo de ejecución. Para los fines de este artículo, se supone que el cliente usará uno de los siguientes flujos de concesión de autorización: código de autorización o credenciales de cliente. Siga las instrucciones de la que mejor se adapte a su escenario para adquirir el token de acceso que usará en las secciones restantes.

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

Tanto los clientes web como los nativos pueden usar esta concesión y requieren credenciales de un usuario que ha iniciado sesión para delegar el acceso a los 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 deberá solicitar un código de autorización de Azure AD. Consulte Solicitud de un código de autorización para obtener más información sobre el formato de la solicitud HTTPS GET al /authorize punto de conexión y mensajes de solicitud/respuesta de ejemplo. El URI contendrá parámetros de cadena de consulta, incluidos los siguientes que son específicos de la aplicación cliente:

    • client_id : también conocido como identificador de aplicación, este es el GUID asignado a la aplicación cliente cuando se registró en la sección anterior.

    • redirect_uri : una versión con codificación URL de [uno de] los URI de respuesta/redireccionamiento especificados durante el registro de la aplicación cliente. Tenga en cuenta que el valor que pase debe coincidir exactamente con el registro.

    • resource : un identificador URI con codificación URL especificado por la API REST que llama. Las API web/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 la administración de servicios clásicas) usanhttps://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. Consulte también la identifierUris propiedad del objeto de aplicación de Azure AD para más información.

    La solicitud al /authorize punto de conexión desencadenará primero un mensaje de inicio de sesión para autenticar al usuario final. La respuesta que recibe se entregará como redireccionamiento (302) al URI especificado en redirect_uri. El mensaje de encabezado de respuesta contendrá un location campo, que contiene el URI de redirección seguido de un code parámetro de consulta, que contiene el código de autorización que necesitará para el paso 2.

  2. A continuación, el cliente tendrá que canjear el código de autorización de un token de acceso. Consulte Uso del código de autorización para solicitar un token de acceso para obtener más información sobre el formato de la solicitud HTTPS POST al /token punto de conexión y mensajes de solicitud y respuesta de ejemplo. Dado que se trata de una solicitud POST, esta vez empaquetará los parámetros específicos de la aplicación en el cuerpo de la solicitud. Además de algunos de los mencionados anteriormente (junto con otros nuevos), pasará :

    • code : este es el parámetro de consulta que contendrá el código de autorización que obtuvo en el paso 1.
    • client_secret : solo necesitará este parámetro si el cliente está configurado como una aplicación web. Este es el mismo valor de secreto/clave que generó anteriormente, en el registro de cliente.

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

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

Las interacciones de cliente o recurso para esta concesión son muy similares al paso 2 de la concesión de código de autorización. Consulte la sección "Solicitar un token de acceso" en Llamadas de servicio a servicio mediante credenciales de cliente para obtener más información sobre el formato de la solicitud HTTPS POST al /token punto de conexión y mensajes de solicitud/respuesta de ejemplo.

Ensamblado del mensaje de solicitud

Tenga en cuenta que 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 clase o API web/HTTP que abstrae la creación o formato de la solicitud, lo que facilita la escritura del código de cliente (es decir, la clase HttpWebRequest en .NET Framework, por ejemplo). Por motivos de brevedad, solo trataremos los elementos importantes de la solicitud, dado que la mayor parte de esto se controlará para usted.

URI de solicitud

Todas las solicitudes REST protegidas requieren el protocolo HTTPS para el esquema de URI, proporcionando la solicitud y la respuesta con un canal seguro, debido al hecho de que se transmite o recibe información confidencial. Esta información (es decir, el código de autorización de Azure AD, el token de acceso o portador, los datos confidenciales de solicitud y 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) los determinará la especificación de la API REST relacionada. Por ejemplo, las API del proveedor de Azure Resource Manager usan https://management.azure.com/, las API clásicas de Azure Service Management usan https://management.core.windows.net/, ambos requieren un api-version parámetro de cadena de consulta, etc.

Encabezado de solicitud

El URI de solicitud se empaquetará en el encabezado del mensaje de solicitud, junto con los campos adicionales determinados por la especificación de la API REST del servicio y la especificación HTTP. Estos son algunos campos de encabezado comunes que puede necesitar en la solicitud:

  • Authorization: contiene el token de portador de OAuth2 para proteger la solicitud, como se adquirió anteriormente de Azure AD.
  • 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: es 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 especificará la codificación y el formato.

El cuerpo de la solicitud está separado del encabezado por una línea vacía, debe tener formato según el campo de Content-Type encabezado. Un ejemplo de un cuerpo con formato "application/json" aparecerá 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 o cuerpo del mensaje de solicitud relacionado, está listo para enviar la solicitud al punto de conexión del servicio REST.

Por ejemplo, un método de solicitud HTTPS GET para un proveedor de Azure Resource Manager podría enviarse mediante campos de encabezado de solicitud similares a los siguientes, pero observe 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 un método de solicitud PUT HTTPS para un proveedor de Azure Resource Manager podría enviarse mediante campos de cuerpo Y encabezado de solicitud similares a los siguientes:

PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/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 devolverá el encabezado del mensaje de respuesta y el cuerpo opcional.

Procesamiento del mensaje de respuesta

Ahora terminaremos con los últimos 2 de los 5 componentes.

Para procesar la respuesta, deberá analizar el encabezado de respuesta y, opcionalmente, el cuerpo de la respuesta (según la solicitud). En el ejemplo HTTPS GET proporcionado anteriormente, usamos el punto de conexión /subscriptions para recuperar la lista de suscripciones de un usuario. Suponiendo que la respuesta se realizó correctamente, deberíamos recibir campos de encabezado de respuesta similares a los siguientes:

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

y un cuerpo de respuesta, que contiene la lista de suscripciones de Azure y sus propiedades individuales codificadas en formato JSON, de forma similar a:

{
    "value":[
        {
        "id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
        "subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
        "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, deberíamos 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 un cuerpo de respuesta, confirmando el contenido de nuestro grupo de recursos recién agregado codificado en formato JSON, similar a:

{
    "id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

Al igual que con la solicitud, la mayoría de los lenguajes de programación o 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 interesará confirmar el código de estado HTTP en el encabezado de respuesta y, si tiene éxito, analizar el cuerpo de la respuesta según la especificación de api (o los campos de Content-Type encabezado de respuesta y Content-Length ).

Eso es todo. Una vez que haya registrado la aplicación de Azure AD y una técnica con componentes para adquirir un token de acceso y crear y procesar solicitudes HTTP, es bastante fácil replicar el código para aprovechar las nuevas API REST.

Contenido relacionado

  • Consulte Plataforma de identidad de Microsoft (Azure Active Directory para desarrolladores) para obtener más información sobre el registro de aplicaciones y el modelo de programación de Azure AD, incluido un índice completo de artículos de HowTo y QuickStart y código de ejemplo.
  • Para 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 respuesta y solicitud HTTP.
    • JWT Decoder y JWT.io, lo que facilita y rápida el volcado de notificaciones en el token de portador para que pueda validar su contenido.

Use la sección de comentarios de LiveFyre que sigue a este artículo para proporcionar comentarios y ayudarnos a refinar y dar forma a nuestro contenido.