Compartir a través de

Realización de solicitudes de API a Azure Stack Hub

  • Artículo

Puede usar las API REST de Azure Stack Hub para automatizar operaciones, como la incorporación de una máquina virtual a la nube de Azure Stack Hub.

La API requiere que el cliente se autentique en el punto de conexión de inicio de sesión de Microsoft Azure. Este punto de conexión devuelve un token en el encabezado de cada solicitud enviada a las API de Azure Stack Hub. Microsoft Azure usa Oauth 2.0.

En este artículo se proporcionan ejemplos que usan la utilidad cURL para crear solicitudes de Azure Stack Hub. cURL es una herramienta de línea de comandos con una biblioteca para transferir datos. Estos ejemplos describen el proceso de recuperación de un token de acceso a las API de Azure Stack Hub. La mayoría de los lenguajes de programación proporcionan bibliotecas Oauth 2.0, que presentan una buena administración de los tokens y controlan tareas tales como la actualización del token.

Examine todo el proceso de utilización de las API REST de Azure Stack Hub con un cliente REST genérico, como cURL, para que le ayude a comprender las solicitudes subyacentes y lo que puede esperar de una carga de respuesta.

En este artículo no se exploran todas las opciones disponibles para recuperar tokens, como el inicio de sesión interactivo o la creación de identificadores de aplicación dedicados. Para obtener información sobre estos temas, consulte Referencia de API REST de Azure.

Obtención de un token de Azure

Cree el cuerpo de la solicitud con el formato de tipo de contenido x-www-form-urlencoded para obtener un token de acceso. Realice una solicitud POST en el punto de conexión de autenticación e inicio de sesión de REST de Azure.

URI

POST https://login.microsoftonline.com/{tenant id}/oauth2/token

El identificador de inquilino es:

  • El dominio del inquilino, como fabrikam.onmicrosoft.com
  • El identificador del inquilino, como aaaabbbb-0000-cccc-1111-dddd2222eeee
  • Valor predeterminado de las claves independientes del inquilino: common

Cuerpo de POST

grant_type=password
&client_id=1950a258-227b-4e31-a9cf-717495945fc2
&resource=https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155
&username=admin@fabrikam.onmicrosoft.com
&password=Password123
&scope=openid

Para cada valor:

  • grant_type:
    El tipo de esquema de autenticación que se va a usar. En este ejemplo, el valor es password.

  • resource:
    El recurso al que accede al token. Para encontrar el recurso, consulte el punto de conexión de metadatos de administración de Azure Stack Hub. Examine la sección audiences.

  • Punto de conexión de administración de Azure Stack Hub:

    https://management.{region}.{Azure Stack Hub domain}/metadata/endpoints?api-version=2015-01-01

    Nota:

    Si es un administrador que intenta acceder a la API de inquilino, asegúrese de usar el punto de conexión del inquilino, por ejemplo https://adminmanagement.{region}.{Azure Stack Hub domain}/metadata/endpoints?api-version=2015-01-011.

    Por ejemplo, con el Kit de desarrollo de Azure Stack como punto de conexión:

    curl 'https://management.local.azurestack.external/metadata/endpoints?api-version=2015-01-01'

    Respuesta:

    {
"galleryEndpoint":"https://adminportal.local.azurestack.external:30015/",
"graphEndpoint":"https://graph.windows.net/",
"portalEndpoint":"https://adminportal.local.azurestack.external/",
"authentication":{
   "loginEndpoint":"https://login.windows.net/",
   "audiences":["https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155"]
   }
}

Ejemplo 1

https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155

  • client_id

    Este valor está codificado en un valor predeterminado:

    1950a258-227b-4e31-a9cf-717495945fc2

    Existen opciones alternativas disponibles para escenarios concretos:

    Application ApplicationID
    LegacyPowerShell 0a7bdc5c-7b57-40be-9939-d4c5fc7cd417
    PowerShell 1950a258-227b-4e31-a9cf-717495945fc2
    WindowsAzureActiveDirectory 00000002-0000-0000-c000-000000000000
    VisualStudio 872cd9fa-d31f-45e0-9eab-6e460a02d1f1
    AzureCLI 04b07795-8ddb-461a-bbee-02f9e1bf7b46

  • username

    Por ejemplo, la cuenta de Microsoft Entra de Azure Stack Hub:

    azurestackadmin@fabrikam.onmicrosoft.com

  • password

    Contraseña de administrador de Microsoft Entra de Azure Stack Hub.

Ejemplo 2

Solicitud:

curl -X "POST" "https://login.windows.net/fabrikam.onmicrosoft.com/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=1950a258-227b-4e31-a9cf-717495945fc2" \
--data-urlencode "grant_type=password" \
--data-urlencode "username=admin@fabrikam.onmicrosoft.com" \
--data-urlencode 'password=Password12345' \
--data-urlencode "resource=https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155"

Respuesta:

{
  "token_type": "Bearer",
  "scope": "user_impersonation",
  "expires_in": "3599",
  "ext_expires_in": "0",
  "expires_on": "1512574780",
  "not_before": "1512570880",
  "resource": "https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155",
  "access_token": "eyJ0eXAiOi...truncated for readability..."
}

Consultas de la API

Una vez que obtenga el token de acceso, agréguelo como un encabezado a todas las solicitudes de API. Para agregarlo como un encabezado, cree un encabezado authorization con el valor: Bearer <access token>. Por ejemplo:

Solicitud:

curl -H "Authorization: Bearer eyJ0eXAiOi...truncated for readability..." 'https://adminmanagement.local.azurestack.external/subscriptions?api-version=2016-05-01'

Respuesta:

offerId : /delegatedProviders/default/offers/92F30E5D-F163-4C58-8F02-F31CFE66C21B
id : /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
subscriptionId : aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e
tenantId : bbbbcccc-1111-dddd-2222-eeee3333ffff
displayName : Default Provider Subscription
state : Enabled
subscriptionPolicies : @{locationPlacementId=AzureStack}

Sintaxis de estructura y consulta de URL

URI de solicitud genérico, que consta de: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}

  • Esquema de URI:
    El URI indica el protocolo usado para enviar la solicitud. Por ejemplo, http o https.
  • Host del URI:
    El host 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 o adminmanagement.local.azurestack.external.
  • Ruta de acceso del recurso:
    La ruta de acceso especifica el recurso o la colección de recursos, que pueden 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 puede usarse para consultar en la lista los propietarios de una aplicación específica dentro de la colección de aplicaciones.
  • Cadena de consulta:
    La cadena proporciona parámetros simples adicionales, como los criterios de selección de versión o recurso de API.

Construcción de URI de solicitud de Azure Stack Hub

{URI-scheme} :// {URI-host} / {subscription id} / {resource group} / {provider} / {resource-path} ? {OPTIONAL: filter-expression} {MANDATORY: api-version}

Sintaxis de URI

https://adminmanagement.local.azurestack.external/{subscription id}/resourcegroups/{resource group}/providers/{provider}/{resource-path}?{api-version}

Ejemplo de consulta de URI

https://adminmanagement.local.azurestack.external/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourcegroups/system.local/providers/microsoft.infrastructureinsights.admin/regionhealths/local/Alerts?$filter=(Properties/State eq 'Active') and (Properties/Severity eq 'Critical')&$orderby=Properties/CreatedTimestamp desc&api-version=2016-05-01"

Pasos siguientes

Para más información sobre el uso de los puntos de conexión REST de Azure, consulte Explorador de API REST.