Referência da API REST do Azure

Bem-vindo à documentação de referência da API REST do Azure.

As APIs REST (Representational State Transfer) são pontos finais de serviço que suportam conjuntos de operações HTTP (métodos), que proporcionam acesso para criar, obter, atualizar ou eliminar os recursos do serviço. Este artigo explica-lhe:

• Como chamar as APIs REST do Azure com curl
• Os componentes básicos de um par de pedidos/respostas da API REST.
• Como registar a aplicação cliente com Microsoft Entra ID para proteger os seus pedidos REST.
• Descrição geral da criação e envio de um pedido REST e processamento da resposta.

Dica

A maioria das APIs REST do serviço do Azure tem bibliotecas de cliente que fornecem uma interface nativa para utilizar os serviços do Azure:

.NET | Java | | Node.jsPython | Ir | C++

Como chamar as APIs REST do Azure com curl

O processo descrito na seguinte publicação de blogue mostra como chamar uma API REST do Azure com curl. Poderá considerar utilizar curl em scripts sem supervisão. Por exemplo, em cenários de automatização de DevOps.

Chamar a API REST do Azure através do curl

Componentes de um pedido/resposta da API REST

Um par pedido/resposta da API REST pode ser separado em cinco componentes:

1. O URI do pedido, que consiste em: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Embora o URI do pedido esteja incluído no cabeçalho da mensagem de pedido, este é chamado separadamente, porque a maioria das linguagens ou estruturas requerem que seja transmitido em separado da mensagem de pedido.

   • Esquema do URI: indica o protocolo utilizado para transmitir o pedido. Por exemplo, http ou https.
   • Anfitrião do URI: especifica o nome de domínio ou o endereço IP do servidor onde o ponto final de serviço REST está alojado, como graph.microsoft.com.
   • Caminho do recurso: especifica o recurso ou coleção de recursos, o 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 (opcional): fornece parâmetros simples adicionais, como a versão da API ou os critérios de seleção de recursos.

2. Campos de cabeçalho de mensagem de pedido HTTP:

   • Um método HTTP obrigatório (também conhecido como uma operação ou verbo), que indica ao serviço que tipo de operação está a pedir. As APIs REST do Azure suportam métodos GET, HEAD, PUT, POST e PATCH.
   • Campos de cabeçalho adicionais opcionais, conforme exigido pelo método URI e HTTP especificado. Por exemplo, um cabeçalho de Autorização que fornece um token de portador que contém informações de autorização de cliente para o pedido.

3. Campos do corpo da mensagem do pedido HTTP opcionais, para suportar a operação URI e HTTP. Por exemplo, as operações POST contêm objetos com codificação MIME transmitidos como parâmetros complexos. Para operações POST ou PUT, o tipo de codificação MIME do corpo também deve ser especificado no cabeçalho do pedido Content-type. Alguns serviços requerem a utilização de um tipo MIME específico, como application/json.

4. Campos de cabeçalho da mensagem de resposta HTTP:

   • Um código de estado HTTP, que varia entre 2xx códigos de êxito e 4xx ou 5xx códigos de erro. Em alternativa, pode ser devolvido um código de estado definido pelo serviço, conforme indicado na documentação da API.
   • Campos de cabeçalho adicionais opcionais, conforme necessário para suportar a resposta do pedido, como um cabeçalho de resposta Content-type.

5. Campos do corpo da mensagem de resposta HTTP opcionais:

   • São devolvidos objetos de resposta com codificação MIME no corpo da resposta HTTP, como uma resposta a um método GET que está a devolver dados. Normalmente, estes objetos são devolvidos num formato estruturado como JSON ou XML, conforme indicado pelo cabeçalho de resposta Content-type. Por exemplo, quando pede um token de acesso de Microsoft Entra ID, este é devolvido no corpo da resposta como o access_token elemento, um dos vários objetos emparelhados de nome/valor numa coleção de dados. Neste exemplo, também está incluído um cabeçalho de resposta de Content-Type: application/json .

Registar a aplicação cliente no Microsoft Entra ID

A maioria dos serviços do Azure (como fornecedores de Resource Manager do Azure e o modelo de implementação clássica) exige que o código de cliente seja autenticado com credenciais válidas antes de poder chamar a API do serviço. A autenticação é coordenada entre os vários atores por Microsoft Entra ID e fornece ao cliente um token de acesso como prova da autenticação. Em seguida, o token é enviado para o serviço do Azure no cabeçalho de Autorização HTTP dos pedidos subsequentes da API REST. As afirmações do token também fornecem informações ao serviço, permitindo-lhe validar o cliente e executar qualquer autorização necessária.

Se estiver a utilizar uma API REST que não utiliza a autenticação Microsoft Entra integrada ou já registou o cliente, avance para a secção Criar o pedido.

Pré-requisitos

A sua aplicação cliente tem de dar a conhecer a respetiva configuração de identidade para Microsoft Entra ID antes do tempo de execução ao registá-la num inquilino Microsoft Entra. Antes de registar o cliente no Microsoft Entra ID, considere os seguintes pré-requisitos:

• Se ainda não tiver um inquilino Microsoft Entra, consulte Configurar um inquilino Microsoft Entra.

• De acordo com o Framework de Autorização OAuth2, Microsoft Entra ID suporta dois tipos de clientes. Compreender cada um ajuda-o a decidir qual é o mais adequado para o seu cenário:

  • Os clientes web/confidenciais são executados num servidor Web e podem aceder a recursos sob a sua própria identidade (por exemplo, um serviço ou daemon) ou obter autorização delegada para aceder a recursos sob a identidade de um utilizador com sessão iniciada (por exemplo, uma aplicação Web). Apenas um cliente Web pode manter e apresentar as suas próprias credenciais de forma segura durante Microsoft Entra autenticação para adquirir um token de acesso.
  • Os clientes nativos/públicos são instalados e executados num dispositivo. Só podem aceder a recursos sob autorização delegada, utilizando a identidade do utilizador com sessão iniciada para adquirir um token de acesso em nome do utilizador.

• O processo de registo cria dois objetos relacionados no inquilino Microsoft Entra onde a aplicação está registada: um objeto de aplicação e um objeto principal de serviço. Para obter mais informações sobre estes componentes e como são utilizados no tempo de execução, veja Objetos de principal de aplicação e de serviço no Microsoft Entra ID.

Está agora pronto para registar a sua aplicação cliente com Microsoft Entra ID.

Registo de cliente

Para registar um cliente que aceda a uma API REST do Azure Resource Manager, veja Utilizar o portal para criar Microsoft Entra aplicação e o principal de serviço que podem aceder aos recursos. O artigo (também disponível nas versões do PowerShell e da CLI para automatizar o registo) mostra-lhe como:

• Registe a aplicação cliente com Microsoft Entra ID.
• Defina pedidos de permissão para permitir que o cliente aceda à API de Resource Manager do Azure.
• Configure as definições do Azure Resource Manager Role-Based Controlo de Acesso (RBAC) para autorizar o cliente.

Se o seu cliente aceder a uma API diferente de uma API de Resource Manager do Azure, veja:

• Registar uma aplicação na plataforma de identidade da Microsoft
  • Registe a aplicação cliente com Microsoft Entra ID, na secção "Registar uma aplicação".
  • Crie uma chave secreta (se estiver a registar um cliente Web), na secção "Adicionar credenciais".
• Configurar uma aplicação para expor uma API Web
  • Adicionar permissões à API Web, expondo-as como âmbitos
• Configurar uma aplicação cliente para aceder a uma API Web
  • Adicione pedidos de permissão conforme necessário pelos âmbitos definidos para a API, na secção "Adicionar permissões para aceder à API Web".

Agora que concluiu o registo da sua aplicação cliente, avance para o código de cliente onde cria o pedido REST e processa a resposta.

Criar o pedido

Esta secção abrange os três primeiros dos cinco componentes que abordámos anteriormente. Primeiro, tem de adquirir o token de acesso do Microsoft Entra ID, que utiliza para montar o cabeçalho da mensagem de pedido.

Adquirir um token de acesso

Depois de ter um registo de cliente válido, tem duas formas de integrar com Microsoft Entra ID para adquirir um token de acesso:

• Pontos finais de serviço OAuth2 neutros em linguagem e plataforma, que utilizamos neste artigo. As instruções fornecidas nesta secção não assumem nada sobre a plataforma ou o idioma/script do cliente quando utiliza os pontos finais do Microsoft Entra OAuth. O único requisito é que pode enviar/receber pedidos HTTPS de/para Microsoft Entra ID e analisar a mensagem de resposta.
• As Bibliotecas de Autenticação da Microsoft (MSAL) específicas da plataforma e da linguagem, que estão fora do âmbito deste artigo. As bibliotecas fornecem wrappers assíncronos para os pedidos de ponto final OAuth2 e funcionalidades robustas de processamento de tokens, como a gestão de tokens de colocação em cache e atualização. Para obter mais informações, veja Descrição Geral da Biblioteca de Autenticação da Microsoft (MSAL).

Os dois pontos finais Microsoft Entra que utiliza para autenticar o cliente e adquirir um token de acesso são referidos como OAuth2 /authorize e /token pontos finais. A forma como as utiliza depende do registo da sua aplicação e do tipo de fluxo de concessão de autorização OAuth2 de que precisa para suportar a sua aplicação em tempo de execução. Para efeitos deste artigo, partimos do princípio de que o cliente utiliza um dos seguintes fluxos de concessão de autorização: código de autorização ou credenciais de cliente. Para adquirir um token de acesso utilizado nas secções restantes, siga as instruções para o fluxo que melhor corresponde ao seu cenário.

Concessão de código de autorização (clientes interativos)

Esta concessão é utilizada por clientes web e nativos, exigindo credenciais de um utilizador com sessão iniciada para delegar o acesso de recursos à aplicação cliente. Utiliza o /authorize ponto final para obter um código de autorização (em resposta ao início de sessão/consentimento do utilizador), seguido do /token ponto final para trocar o código de autorização por um token de acesso.

1. Primeiro, o cliente tem de pedir um código de autorização ao Microsoft Entra ID. Para obter detalhes sobre o formato do pedido HTTPS GET para o /authorize ponto final e mensagens de pedido/resposta de exemplo, veja Pedir um código de autorização. O URI contém os seguintes parâmetros de cadeia de consulta, que são específicos da sua aplicação cliente:

   • client_id: um GUID que foi atribuído à aplicação cliente durante o registo, também conhecido como ID da aplicação.

   • redirect_uri: uma versão codificada por URL de um dos URIs de resposta/redirecionamento, especificada durante o registo da aplicação cliente. O valor que transmitir tem de corresponder exatamente ao seu valor de registo.

   • resource: um URI de identificador codificado por URL especificado pela API REST que está a chamar. As APIs Web/REST (também conhecidas como aplicações de recursos) podem expor um ou mais URIs de ID de aplicação na respetiva configuração. Por exemplo:

     • As APIs do fornecedor de Resource Manager do Azure (e do modelo de implementação clássica) utilizam https://management.core.windows.net/.
     • Para quaisquer outros recursos, veja a documentação da API ou a configuração da aplicação de recursos no portal do Azure. Para obter mais informações, veja a identifierUris propriedade do objeto da aplicação Microsoft Graph API.

   O pedido para o /authorize ponto final aciona primeiro um pedido de início de sessão para autenticar o utilizador. A resposta que receber é entregue como um redirecionamento (302) para o URI que especificou em redirect_uri. A mensagem de cabeçalho de resposta contém um location campo, que contém o URI de redirecionamento seguido de um code parâmetro de consulta. O code parâmetro contém o código de autorização necessário para o passo 2.

2. Em seguida, o cliente tem de resgatar o código de autorização para um token de acesso. Para obter detalhes sobre o formato do pedido HTTPS POST para o /token ponto final e exemplos de pedido/resposta, veja Pedir um token de acesso. Uma vez que se trata de um pedido POST, empacota os parâmetros específicos da aplicação no corpo do pedido. Além de alguns dos parâmetros mencionados anteriormente (juntamente com outros novos), irá transmitir:

   • code: este parâmetro de consulta contém o código de autorização que obteve no passo 1.

   • client_secret: só precisa deste parâmetro se o cliente estiver configurado como uma aplicação Web. Este é o mesmo valor de segredo/chave que gerou anteriormente, no registo de cliente.

Concessão de credenciais de cliente (clientes não interativos)

Esta concessão é utilizada apenas por clientes Web, permitindo que a aplicação aceda diretamente aos recursos (sem delegação de utilizador) com as credenciais do cliente, que são fornecidas no momento do registo. Normalmente, a concessão é utilizada por clientes não interativos (sem IU) que são executados como um serviço ou daemon. Requer apenas o /token ponto final para adquirir um token de acesso.

As interações cliente/recurso para esta concessão são semelhantes ao passo 2 da concessão do código de autorização. Para obter detalhes sobre o formato do pedido HTTPS POST para o /token ponto final e exemplos de pedido/resposta, veja a secção "Obter um token" no plataforma de identidades da Microsoft e o fluxo de credenciais de cliente OAuth 2.0.

Reunir a mensagem de pedido

A maioria das linguagens ou arquiteturas de programação e ambientes de scripting facilitam a montagem e o envio da mensagem de pedido. Normalmente, fornecem uma classe Web/HTTP ou API que abstrai a criação ou formatação do pedido, facilitando a escrita do código de cliente (a HttpWebRequest classe no .NET Framework, por exemplo). Por questões de brevidade, e uma vez que a maior parte da tarefa é processada por si, esta secção abrange apenas os elementos importantes do pedido.

URI do pedido

Uma vez que as informações confidenciais estão a ser transmitidas e recebidas, todos os pedidos REST requerem o protocolo HTTPS para o esquema de URI, dando ao pedido e à resposta um canal seguro. As informações (ou seja, o código de autorização Microsoft Entra, o token de acesso/portador e os dados confidenciais de pedido/resposta) são encriptadas por uma camada de transporte inferior, garantindo a privacidade das mensagens.

O resto do URI do pedido do serviço (o anfitrião, o caminho do recurso e quaisquer parâmetros de cadeia de consulta necessários) são determinados pela especificação da API REST relacionada. Por exemplo, as APIs do fornecedor do Azure Resource Manager utilizam https://management.azure.com/e o modelo de implementação clássica do Azure utiliza https://management.core.windows.net/. Ambos requerem um api-version parâmetro de cadeia de consulta.

Cabeçalho do pedido

O URI do pedido é agrupado no cabeçalho da mensagem de pedido, juntamente com quaisquer campos adicionais exigidos pela especificação da API REST do seu serviço e pela especificação HTTP. O pedido pode exigir os seguintes campos de cabeçalho comuns:

• Authorization: contém o token de portador OAuth2 para proteger o pedido, conforme adquirido anteriormente ao Microsoft Entra ID.
• Content-Type: normalmente definido como "application/json" (pares nome/valor no formato JSON) e especifica o tipo MIME do corpo do pedido.
• Host: o nome de domínio ou endereço IP do servidor onde o ponto final de serviço REST está alojado.

Corpo do pedido

Conforme mencionado anteriormente, o corpo da mensagem do pedido é opcional, consoante a operação específica que está a pedir e os respetivos requisitos de parâmetros. Se for necessário, a especificação da API para o serviço que está a pedir também especifica a codificação e o formato.

O corpo do pedido é separado do cabeçalho por uma linha vazia, formatada de acordo com o campo de Content-Type cabeçalho. Um exemplo de um corpo formatado "application/json" seria apresentado da seguinte forma:

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

Enviar o pedido

Agora que tem o URI do pedido do serviço e criou o cabeçalho e o corpo da mensagem de pedido relacionados, está pronto para enviar o pedido para o ponto final de serviço REST.

Por exemplo, pode enviar um método de pedido HTTPS GET para um fornecedor de Resource Manager do Azure com campos de cabeçalho de pedido semelhantes aos seguintes (tenha em atenção que o corpo do pedido está vazio):

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

<no body>

Além disso, pode enviar um método de pedido HTTPS PUT para um fornecedor de Resource Manager do Azure com campos de cabeçalho e corpo de pedido semelhantes ao seguinte exemplo:

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

Depois de fazer o pedido, o cabeçalho da mensagem de resposta e o corpo opcional são devolvidos.

Processar a mensagem de resposta

O processo termina com os dois últimos dos cinco componentes.

Para processar a resposta, analise o cabeçalho de resposta e, opcionalmente, o corpo da resposta (dependendo do pedido). No exemplo HTTPS GET fornecido na secção anterior, utilizou o ponto final /subscriptions para obter a lista de subscrições de um utilizador. Partindo do princípio de que a resposta foi bem-sucedida, deve receber campos de cabeçalho de resposta semelhantes ao seguinte exemplo:

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

Além disso, deverá receber um corpo de resposta que contém uma lista de subscrições do Azure e as respetivas propriedades individuais codificadas no formato JSON, semelhante a:

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

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

Da mesma forma, para o exemplo HTTPS PUT, deve receber um cabeçalho de resposta semelhante ao seguinte, confirmando que a operação PUT para adicionar o "ExampleResourceGroup" foi bem-sucedida:

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

Além disso, deverá receber um corpo de resposta que confirme o conteúdo do grupo de recursos recém-adicionado codificado no formato JSON, semelhante a:

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

Tal como acontece com o pedido, a maioria das linguagens e arquiteturas de programação facilita o processamento da mensagem de resposta. Normalmente, estas informações são devolvidas à sua aplicação após o pedido, permitindo-lhe processá-la num formato escrito/estruturado. Principalmente, está interessado em confirmar o código de estado HTTP no cabeçalho da resposta e analisar o corpo da resposta de acordo com a especificação da API (ou os campos de Content-Type cabeçalho e Content-Length de resposta).

Operações assíncronas, limitação e paginação

O padrão Create/Send/Process-Response abordado neste artigo é síncrono e aplica-se a todas as mensagens REST. No entanto, alguns serviços também suportam um padrão assíncrono, que requer processamento adicional de cabeçalhos de resposta para monitorizar ou concluir o pedido assíncrono. Para obter mais informações, veja Controlar operações assíncronas do Azure.

Resource Manager aplica um limite ao número de pedidos de leitura e escrita por hora para impedir que uma aplicação envie demasiados pedidos. Se a aplicação exceder esses limites, os pedidos serão limitados. O cabeçalho de resposta inclui o número de pedidos restantes para o âmbito. Para obter mais informações, veja Estrangulamento de pedidos do Resource Manager.

Algumas operações de lista devolvem uma propriedade chamada nextLink no corpo da resposta. Verá esta propriedade quando os resultados são demasiado grandes para serem devolvidos numa resposta. Normalmente, a resposta inclui a propriedade nextLink quando a operação de lista devolve mais de 1000 itens. Quando nextLink não estiver presente nos resultados, os resultados devolvidos serão concluídos. Quando nextLink contém um URL, os resultados devolvidos são apenas parte do conjunto de resultados total.

A resposta está no formato:

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

Para obter a página seguinte dos resultados, envie um pedido GET para o URL na propriedade nextLink. O URL inclui um token de continuação para indicar onde está nos resultados. Continue a enviar pedidos para o URL nextLink até deixar de conter um URL nos resultados devolvidos.

Resiliência das APIs do Azure

As APIs REST do Azure foram concebidas para resiliência e disponibilidade contínua. As operações do plano de controlo (pedidos enviados para management.azure.com) na API REST são:

• Distribuído entre regiões. Alguns serviços são regionais.

• Distribuído por Zonas de Disponibilidade (bem como por regiões) em localizações com várias Zonas de Disponibilidade.

• Não dependente de um único datacenter lógico.

• Nunca retirado para atividades de manutenção.

Conteúdo relacionado

Já está. Depois de registar a sua aplicação Microsoft Entra e ter uma técnica modular para adquirir um token de acesso e processar pedidos HTTP, é bastante fácil replicar o código para tirar partido das novas APIs REST. Para obter mais informações sobre o registo de aplicações e o modelo de programação Microsoft Entra, veja a documentação do plataforma de identidades da Microsoft.

Para obter informações sobre como testar pedidos/respostas HTTP, consulte:

• Fiddler. O Fiddler é um proxy de depuração Web gratuito que pode intercetar os pedidos REST, o que facilita o diagnóstico das mensagens de pedido/resposta HTTP.
• JWT.ms, o que torna mais rápido e fácil capturar as afirmações no token de portador para que possa validar os respetivos conteúdos.