Fazer solicitações de API para Azure Stack Hub

Você pode usar as APIs REST do hub de Azure Stack para automatizar operações, como adicionar uma VM (máquina virtual) à sua nuvem de Azure Stack Hub.

as APIs exigem que o cliente se autentique no ponto de extremidade de entrada do Microsoft Azure. O ponto de extremidade retorna um token a ser usado no cabeçalho de cada solicitação enviada para as APIs do hub de Azure Stack. Microsoft Azure usa o Oauth 2,0.

Este artigo fornece exemplos que usam o utilitário de rotação para criar Azure Stack solicitações de Hub. a ondulação é uma ferramenta de linha de comando com uma biblioteca para transferência de dados. Esses exemplos descrevem o processo de recuperação de um token para acessar as APIs do hub de Azure Stack. A maioria das linguagens de programação fornece bibliotecas do OAuth 2,0, que têm gerenciamento de token robusto e gerenciam tarefas como a atualização do token.

Examine todo o processo de uso das APIs REST do hub de Azure Stack com um cliente REST genérico, como ondulação, para ajudá-lo a entender as solicitações subjacentes e o que você pode esperar em uma carga de resposta.

Este artigo não explora todas as opções disponíveis para recuperar Tokens, como entrada interativa ou criação de IDs de aplicativo dedicadas. Para obter informações sobre esses tópicos, consulte a referência da API REST do Azure.

Obter um token do Azure

Crie um corpo de solicitação formatado usando o tipo de conteúdo x-www-form-urlencoded para obter um token de acesso. POSTE sua solicitação para o ponto de extremidade de logon e autenticação REST do Azure.

URI

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

A ID do locatário é:

  • Seu domínio de locatário, como fabrikam.onmicrosoft.com
  • Sua ID de locatário, como 8eaed023-2b34-4da1-9baa-8bc8c9d6a491
  • Valor padrão para chaves independentes de locatário: common

Corpo da postagem

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 você usará. Neste exemplo, o valor é password .

  • recurso:
    O recurso que o token acessa. Você pode encontrar o recurso consultando o ponto de extremidade de metadados de gerenciamento de Hub Azure Stack. Examine a seção audiências .

  • Ponto de extremidade de gerenciamento de Hub Azure Stack:

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

    Observação

    Se você for um administrador tentando acessar a API de locatário, certifique-se de usar o ponto de extremidade do locatário; por exemplo, https://adminmanagement.{region}.{Azure Stack Hub domain}/metadata/endpoints?api-version=2015-01-011 .

    Por exemplo, com o Kit de Desenvolvimento do Azure Stack (ASDK) como um ponto de extremidade:

    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

    Esse valor é codificado para um valor padrão:

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

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

    Aplicativo 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 exemplo, a conta Azure Stack Hub do Azure AD:

    azurestackadmin@fabrikam.onmicrosoft.com
    
  • password

    A senha de administrador do Azure AD do Azure Stack Hub.

Exemplo 2

Solicitação:

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 uma de suas solicitações de API. Para adicioná-lo como um cabeçalho, crie um cabeçalho de autorização com o valor: . Por exemplo:

Solicitação:

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

URI de solicitação genérica, consiste em: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}

  • Esquema de URI:
    O URI indica o protocolo usado para enviar a solicitação. Por exemplo, http ou https.
  • Host URI:
    O host especifica o nome de domínio ou o endereço IP do servidor no qual o ponto de extremidade do serviço REST está hospedado, como graph.microsoft.com ou adminmanagement.local.azurestack.external .
  • Caminho do recurso:
    O caminho Especifica a coleção de recursos ou recursos, que pode incluir vários segmentos usados pelo serviço para determinar a seleção desses recursos. Por exemplo: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners pode ser usado para consultar a lista de proprietários de um aplicativo específico na coleção de aplicativos.
  • Cadeia de caracteres de consulta:
    A cadeia de caracteres fornece parâmetros simples adicionais, como a versão da API ou os critérios de seleção de recursos.

Construção de URI de solicitação de Hub de Azure Stack

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

Sintaxe 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"

Próximas etapas

Para obter mais informações sobre como usar os pontos de extremidade REST do Azure, consulte a referência da API REST do Azure.