Partilhar via

Criar pedidos da API ao Azure Stack Hub

  • Artigo

Pode utilizar as APIs REST do Azure Stack Hub para automatizar operações, como adicionar uma máquina virtual (VM) à cloud do Azure Stack Hub.

As APIs exigem que o cliente se autentique no ponto final de início de sessão do Microsoft Azure. O ponto final devolve um token a utilizar no cabeçalho de cada pedido enviado para as APIs do Azure Stack Hub. O Microsoft Azure utiliza o Oauth 2.0.

Este artigo fornece exemplos que utilizam o utilitário cURL para criar pedidos do Azure Stack Hub. O cURL é uma ferramenta de linha de comandos com uma biblioteca para transferir dados. Estes exemplos descrevem o processo de obtenção de um token para aceder às APIs do Azure Stack Hub. A maioria das linguagens de programação fornece bibliotecas Oauth 2.0, que têm uma gestão de tokens robusta e processam tarefas como atualizar o token.

Reveja todo o processo de utilização das APIs REST do Azure Stack Hub com um cliente REST genérico, como o cURL, para o ajudar a compreender os pedidos subjacentes e o que pode esperar num payload de resposta.

Este artigo não explora todas as opções disponíveis para obter tokens, como o início de sessão interativo ou a criação de IDs de aplicações dedicados. Para obter informações sobre estes tópicos, veja Referência da API REST do Azure.

Obter um token do Azure

Crie um corpo do pedido formatado com o tipo x-www-form-urlencoded de conteúdo para obter um token de acesso. PUBLIQUE o seu pedido para o ponto final de início de sessão e autenticação REST do Azure.

URI

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

O ID do Inquilino é:

  • O seu domínio de inquilino, como fabrikam.onmicrosoft.com
  • O seu ID de inquilino, como 8eaed023-2b34-4da1-9baa-8bc8c9d6a491
  • Valor predefinido para chaves independentes do inquilino: common

Corpo da publicação

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:
    O tipo de esquema de autenticação que irá utilizar. Neste exemplo, o valor é password.

  • recurso:
    O recurso a que o token acede. Pode encontrar o recurso ao consultar o ponto final de metadados de gestão do Azure Stack Hub. Observe a secção audiências .

  • Ponto final de gestão do Azure Stack Hub:

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

    Nota

    Se for um administrador a tentar aceder à API de inquilino, certifique-se de que utiliza o ponto final do inquilino; por exemplo, https://adminmanagement.{region}.{Azure Stack Hub domain}/metadata/endpoints?api-version=2015-01-011.

    Por exemplo, com o Azure Stack Development Kit (ASDK) como um ponto final:

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

    Resposta:

    {
"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"]
   }
}

Exemplo 1

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

  • client_id

    Este valor está codificado para um valor predefinido:

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

    Estão disponíveis opções alternativas para cenários específicos:

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

  • nome de utilizador

    Por exemplo, a conta de Microsoft Entra do Azure Stack Hub:

    azurestackadmin@fabrikam.onmicrosoft.com

  • palavra-passe

    A palavra-passe de administrador Microsoft Entra do Azure Stack Hub.

Exemplo 2

Pedido:

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"

Resposta:

{
  "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 API

Depois de obter o token de acesso, adicione-o como um cabeçalho a cada um dos seus pedidos de API. Para adicioná-lo como um cabeçalho, crie um cabeçalho de autorização com o valor : Bearer <access token>. Por exemplo:

Pedido:

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

Resposta:

offerId : /delegatedProviders/default/offers/92F30E5D-F163-4C58-8F02-F31CFE66C21B
id : /subscriptions/800c4168-3eb1-406b-a4ca-919fe7ee42e8
subscriptionId : 800c4168-3eb1-406b-a4ca-919fe7ee42e8
tenantId : 9fea4606-7c07-4518-9f3f-8de9c52ab628
displayName : Default Provider Subscription
state : Enabled
subscriptionPolicies : @{locationPlacementId=AzureStack}

Estrutura de URL e sintaxe de consulta

O URI do pedido genérico consiste em: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}

  • Esquema URI:
    O URI indica o protocolo utilizado para enviar o pedido. Por exemplo, http ou https.
  • Anfitrião de URI:
    O anfitrião especifica o nome de domínio ou endereço IP do servidor onde o ponto final de serviço REST está alojado, como graph.microsoft.com ou adminmanagement.local.azurestack.external.
  • Caminho do recurso:
    O caminho especifica o recurso ou a coleção de recursos, que pode incluir vários segmentos utilizados pelo serviço para determinar a seleção desses recursos. Por exemplo: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners pode ser utilizado para consultar a lista de proprietários de uma aplicação específica na coleção de aplicações.
  • Cadeia de consulta:
    A cadeia fornece parâmetros simples adicionais, como a versão da API ou os critérios de seleção de recursos.

Construção do URI do pedido do Azure Stack Hub

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

Sintaxe do URI

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

Exemplo de URI de consulta

https://adminmanagement.local.azurestack.external/subscriptions/800c4168-3eb1-406b-a4ca-919fe7ee42e8/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"

Passos seguintes

Para obter mais informações sobre como utilizar os pontos finais REST do Azure, veja Referência da API REST do Azure.