Referência da API REST do Azure

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

As APIs REST (Transferência de Estado Representacional) são pontos de extremidade de serviço que dão suporte a conjuntos de operações HTTP (métodos), que fornecem acesso de criação, recuperação, atualização ou exclusão para recursos de serviço. Este artigo orienta você sobre:

• Como chamar APIs REST do Azure com curl
• Os componentes básicos de um par de solicitação/resposta da API REST.
• Como registrar seu aplicativo cliente com Microsoft Entra ID para proteger suas solicitações REST.
• Visões gerais de criação e envio de uma solicitação REST e manipulação da resposta.

Dica

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

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

Como chamar APIs REST do Azure com curl

O processo descrito na postagem de blog a seguir mostra como chamar uma API REST do Azure usando curl. Você pode considerar o uso de curl em scripts autônomos. Por exemplo, em cenários de automação de DevOps.

Chamando a API REST do Azure via curl

Componentes de uma solicitação/resposta da API REST

Um par de solicitação/resposta da API REST pode ser separado em cinco componentes:

1. O URI de solicitação, que consiste em {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Embora o URI de solicitação seja incluído no cabeçalho da mensagem de solicitação, chamamos o URI separadamente aqui porque a maioria das linguagens ou estruturas exige que ele seja passado separadamente da mensagem de solicitação.

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

2. Campos de cabeçalho de mensagem de solicitação HTTP:

   • Um método HTTP necessário (também conhecido como operação ou verbo), que informa ao serviço que tipo de operação você está solicitando. As APIs REST do Azure dão suporte aos métodos GET, HEAD, PUT, POST e PATCH.
   • Campos de cabeçalho adicionais opcionais, conforme exigido pelo URI e método HTTP especificados. Por exemplo, um cabeçalho authorization que fornece um token de portador que contém informações de autorização do cliente para a solicitação.

3. Campos opcionais de corpo da mensagem de solicitação HTTP, para dar suporte à operação de URI e HTTP. Por exemplo, as operações POST contêm objetos codificado em MIME que são passados como parâmetros complexos. Para operações POST ou PUT, o tipo de codificação MIME do corpo deve ser especificado também no cabeçalho de solicitação Content-type. Alguns serviços exigem o uso de um tipo MIME específico, como application/json.

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

   • Um código de status HTTP, que varia de códigos de sucesso 2xx a códigos de erro 4xx ou 5xx. Como alternativa, um código de status definido pelo serviço pode ser retornado, conforme indicado na documentação da API.
   • Campos de cabeçalho adicionais opcionais, conforme necessário, para dar suporte à resposta da solicitação, como um cabeçalho de resposta Content-type.

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

   • Os objetos de resposta codificados em MIME são retornados no corpo da resposta HTTP, como uma resposta de um método GET que está retornando dados. Normalmente, esses objetos são retornados em um formato estruturado como JSON ou XML, conforme indicado pelo cabeçalho de resposta Content-type. Por exemplo, quando você solicita um token de acesso de Microsoft Entra ID, ele é retornado no corpo da resposta como o access_token elemento , um dos vários objetos emparelhados nome/valor em uma coleção de dados. Neste exemplo, um cabeçalho de resposta de Content-Type: application/json também está incluído.

Registrar seu aplicativo cliente com Microsoft Entra ID

A maioria dos serviços do Azure (como provedores de Resource Manager do Azure e o modelo de implantação clássico) exige que o código do cliente se autentique com credenciais válidas antes que você possa 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 autorização HTTP das solicitações subsequentes da API REST. As declarações do token também fornecem informações ao serviço, permitindo que ele valide o cliente e execute qualquer autorização necessária.

Se você estiver usando uma API REST que não usa a autenticação Microsoft Entra integrada ou já registrou seu cliente, vá para a seção Criar a solicitação.

Pré-requisitos

Seu aplicativo cliente deve tornar sua configuração de identidade conhecida por Microsoft Entra ID antes do tempo de execução registrando-a em um locatário Microsoft Entra. Antes de registrar seu cliente com Microsoft Entra ID, considere os seguintes pré-requisitos:

• Se você ainda não tiver um locatário Microsoft Entra, consulte Configurar um locatário Microsoft Entra.

• De acordo com a Estrutura de Autorização OAuth2, Microsoft Entra ID dá suporte a dois tipos de clientes. Entender cada um ajuda você a decidir qual é o mais apropriado para seu cenário:

  • Os clientes web/confidenciais são executados em um servidor Web e podem acessar recursos em sua própria identidade (por exemplo, um serviço ou daemon) ou obter autorização delegada para acessar recursos sob a identidade de um usuário conectado (por exemplo, um aplicativo Web). Somente um cliente Web pode manter e apresentar com segurança suas próprias credenciais durante Microsoft Entra autenticação para adquirir um token de acesso.
  • clientes nativos/públicos são instalados e executados em um dispositivo. Eles só podem acessar recursos sob autorização delegada, usando a identidade do usuário conectado para adquirir um token de acesso em nome do usuário.

• O processo de registro cria dois objetos relacionados no locatário Microsoft Entra em que o aplicativo está registrado: um objeto de aplicativo e um objeto de entidade de serviço. Para obter mais informações sobre esses componentes e como eles são usados em tempo de execução, consulte Objetos de aplicativo e entidade de serviço no Microsoft Entra ID.

Agora você está pronto para registrar seu aplicativo cliente com Microsoft Entra ID.

Registro do cliente

Para registrar um cliente que acessa uma API REST Resource Manager do Azure, confira Usar o portal para criar Microsoft Entra aplicativo e entidade de serviço que podem acessar recursos. O artigo (também disponível no PowerShell e nas versões da CLI para automatizar o registro) mostra como:

• Registre o aplicativo cliente com Microsoft Entra ID.
• Defina solicitações de permissão para permitir que o cliente acesse a API de Resource Manager do Azure.
• Defina as configurações do RBAC (Azure Resource Manager Role-Based Controle de Acesso) para autorizar o cliente.

Se o cliente acessar uma API diferente de uma API de Resource Manager do Azure, consulte:

• Registrar um aplicativo com a Microsoft Identity Platform
  • Registre o aplicativo cliente com Microsoft Entra ID, na seção "Registrar um aplicativo".
  • Crie uma chave secreta (se você estiver registrando um cliente Web) na seção "Adicionar credenciais".
• Configurar um aplicativo para expor uma API Web
  • Adicionar permissões à API Web, expondo-as como escopos
• Configurar um aplicativo cliente para acessar uma API Web
  • Adicione solicitações de permissão conforme exigido pelos escopos definidos para a API, na seção "Adicionar permissões para acessar sua API Web".

Agora que você concluiu o registro do aplicativo cliente, vá para o código do cliente em que você cria a solicitação REST e manipula a resposta.

Criar a solicitação

Esta seção aborda os três primeiros dos cinco componentes que discutimos anteriormente. Primeiro, você precisa adquirir o token de acesso do Microsoft Entra ID, que você usa para montar o cabeçalho da mensagem de solicitação.

Adquirir um token de acesso

Depois de ter um registro de cliente válido, você terá duas maneiras de se integrar ao Microsoft Entra ID para adquirir um token de acesso:

• Pontos de extremidade de serviço OAuth2 de plataforma e idioma neutro, que usamos neste artigo. As instruções fornecidas nesta seção não pressupõem nada sobre a plataforma ou idioma/script do cliente quando você usa os pontos de extremidade OAuth Microsoft Entra. O único requisito é que você possa enviar/receber solicitações HTTPS de/para Microsoft Entra ID e analisar a mensagem de resposta.
• As MSAL (Bibliotecas de Autenticação da Microsoft) específicas da plataforma e da linguagem, que está além do escopo deste artigo. As bibliotecas fornecem wrappers assíncronos para as solicitações de ponto de extremidade OAuth2 e recursos robustos de manipulação de token, como armazenamento em cache e gerenciamento de token de atualização. Para obter mais informações, consulte a Visão geral da MSAL (Biblioteca de Autenticação da Microsoft).

Os dois pontos de extremidade Microsoft Entra que você usa para autenticar seu cliente e adquirir um token de acesso são chamados de OAuth2 /authorize e /token pontos de extremidade. A maneira como você os usa depende do registro do aplicativo e do tipo de fluxo de concessão de autorização OAuth2 necessário para dar suporte ao aplicativo em tempo de execução. Para os fins deste artigo, supomos que seu cliente use 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 usado nas seçõ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)

Essa concessão é usada por clientes web e nativos, exigindo credenciais de um usuário conectado para delegar acesso de recursos ao aplicativo cliente. Ele usa o /authorize ponto de extremidade para obter um código de autorização (em resposta à entrada/consentimento do /token usuário), seguido pelo ponto de extremidade para trocar o código de autorização por um token de acesso.

1. Primeiro, o cliente precisa solicitar um código de autorização do Microsoft Entra ID. Para obter detalhes sobre o formato da solicitação HTTPS GET para o /authorize ponto de extremidade e exemplos de mensagens de solicitação/resposta, consulte Solicitar um código de autorização. O URI contém os seguintes parâmetros de cadeia de caracteres de consulta, que são específicos para seu aplicativo cliente:

   • client_id: um GUID que foi atribuído ao aplicativo cliente durante o registro, também conhecido como ID do aplicativo.

   • redirect_uri: uma versão codificada em URL de uma das URIs de resposta/redirecionamento, especificada durante o registro do aplicativo cliente. O valor que você passa deve corresponder exatamente ao seu valor de registro.

   • resource: um URI de identificador codificado em URL especificado pela API REST que você está chamando. AS APIs Web/REST (também conhecidas como aplicativos de recurso) podem expor um ou mais URIs de ID do aplicativo em sua configuração. Por exemplo:

     • As APIs do provedor de Resource Manager do Azure (e do modelo de implantação clássico) usam https://management.core.windows.net/.
     • Para quaisquer outros recursos, consulte a documentação da API ou a configuração do aplicativo de recurso no portal do Azure. Para obter mais informações, consulte a identifierUris propriedade do objeto de aplicativo do Microsoft API do Graph.

   A solicitação para o /authorize ponto de extremidade primeiro dispara um prompt de entrada para autenticar o usuário. A resposta que você obtém é entregue como um redirecionamento (302) para o URI especificado em redirect_uri. A mensagem de cabeçalho de resposta contém um location campo que contém o URI de redirecionamento seguido por um code parâmetro de consulta. O code parâmetro contém o código de autorização necessário para a etapa 2.

2. Em seguida, seu cliente precisa resgatar o código de autorização para um token de acesso. Para obter detalhes sobre o formato da solicitação HTTPS POST para o /token ponto de extremidade e exemplos de solicitação/resposta, consulte Solicitar um token de acesso. Como essa é uma solicitação POST, você empacota os parâmetros específicos do aplicativo no corpo da solicitação. Além de alguns dos parâmetros mencionados anteriormente (juntamente com outros novos), você passará:

   • code: esse parâmetro de consulta contém o código de autorização obtido na etapa 1.

   • client_secret: você precisará desse parâmetro somente se o cliente estiver configurado como um aplicativo Web. Esse é o mesmo valor de segredo/chave que você gerou anteriormente, no registro do cliente.

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

Essa concessão é usada somente por clientes Web, permitindo que o aplicativo acesse recursos diretamente (sem delegação de usuário) usando as credenciais do cliente, que são fornecidas no momento do registro. A concessão normalmente é usada por clientes não interativos (sem interface do usuário) que são executados como um serviço ou daemon. Ele requer apenas o /token ponto de extremidade para adquirir um token de acesso.

As interações de cliente/recurso para essa concessão são semelhantes à etapa 2 da concessão de código de autorização. Para obter detalhes sobre o formato da solicitação HTTPS POST para o /token ponto de extremidade e exemplos de solicitação/resposta, consulte a seção "Obter um token" em plataforma de identidade da Microsoft e o fluxo de credenciais do cliente OAuth 2.0.

Montar a mensagem de solicitação

A maioria das linguagens de programação ou estruturas e ambientes de script facilita a montagem e o envio da mensagem de solicitação. Normalmente, eles fornecem uma classe Web/HTTP ou uma API que abstrai a criação ou a formatação da solicitação, facilitando a gravação do código do cliente (a HttpWebRequest classe no .NET Framework, por exemplo). Para fins de brevidade e como a maior parte da tarefa é tratada para você, esta seção aborda apenas os elementos importantes da solicitação.

URI da solicitação

Como as informações confidenciais estão sendo transmitidas e recebidas, todas as solicitações REST exigem o protocolo HTTPS para o esquema de URI, dando à solicitação 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 solicitação/resposta) são criptografadas por uma camada de transporte inferior, garantindo a privacidade das mensagens.

O restante do URI de solicitação do serviço (o host, o caminho do recurso e todos os parâmetros de cadeia de caracteres de consulta necessários) é determinado pela especificação da API REST relacionada. Por exemplo, as APIs do provedor de Resource Manager do Azure usam https://management.azure.com/e o modelo de implantação clássico do Azure usa https://management.core.windows.net/. Ambos exigem um api-version parâmetro de cadeia de caracteres de consulta.

Cabeçalho da solicitação

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

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

Corpo da solicitação

Conforme mencionado anteriormente, o corpo da mensagem de solicitação é opcional, dependendo da operação específica que você está solicitando e seus requisitos de parâmetro. Se for necessário, a especificação de API para o serviço que você está solicitando também especificará a codificação e o formato.

O corpo da solicitação é 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 exibido da seguinte maneira:

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

Enviar a solicitação

Agora que você tem o URI de solicitação do serviço e criou o cabeçalho e o corpo da mensagem de solicitação relacionados, você está pronto para enviar a solicitação para o ponto de extremidade de serviço REST.

Por exemplo, você pode enviar um método de solicitação HTTPS GET para um provedor de Resource Manager do Azure usando campos de cabeçalho de solicitação semelhantes aos seguintes (observe que o corpo da solicitação está vazio):

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

<no body>

E você pode enviar um método de solicitação HTTPS PUT para um provedor de Resource Manager do Azure usando campos de cabeçalho e corpo da solicitação semelhantes ao exemplo a seguir:

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 a solicitação, o cabeçalho da mensagem de resposta e o corpo opcional são retornados.

Processar a mensagem de resposta

O processo é concluído com os dois últimos dos cinco componentes.

Para processar a resposta, analise o cabeçalho de resposta e, opcionalmente, o corpo da resposta (dependendo da solicitação). No exemplo HTTPS GET fornecido na seção anterior, você usou o ponto de extremidade /subscriptions para recuperar a lista de assinaturas de um usuário. Supondo que a resposta foi bem-sucedida, você deve receber campos de cabeçalho de resposta semelhantes ao exemplo a seguir:

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

E você deve receber um corpo de resposta que contenha uma lista de assinaturas do Azure e suas 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, você 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;

E você deve 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"
        }
}

Assim como acontece com a solicitação, a maioria das linguagens e estruturas de programação facilita o processamento da mensagem de resposta. Normalmente, elas retornam essas informações ao seu aplicativo após a solicitação, permitindo que você as processe em um formato tipado/estruturado. Principalmente, você está interessado em confirmar o código de status HTTP no cabeçalho de resposta e analisar o corpo da resposta de acordo com a especificação da API (ou os campos de Content-Type cabeçalho de resposta e Content-Length ).

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

O padrão Create/Send/Process-Response discutido neste artigo é síncrono e se aplica a todas as mensagens REST. No entanto, alguns serviços também dão suporte a um padrão assíncrono, que requer processamento adicional de cabeçalhos de resposta para monitorar ou concluir a solicitação assíncrona. Para obter mais informações, consulte Rastrear operações assíncronas de Azure.

Resource Manager aplica um limite no número de solicitações de leitura e gravação por hora para impedir que um aplicativo envie muitas solicitações. Se o aplicativo exceder esses limites, as solicitações serão limitadas. O cabeçalho de resposta inclui o número de solicitações restantes para seu escopo. Para saber mais, confira Limitar solicitação do Resource Manager.

Algumas operações de lista retornam uma propriedade chamada nextLink no corpo da resposta. Você verá essa propriedade quando os resultados forem muito grandes para retornar em uma resposta. Normalmente, a resposta inclui a propriedade nextLink quando a operação de lista retorna mais de 1.000 itens. Quando nextLink não estiver presente nos resultados, os resultados retornados serão concluídos. Quando nextLink contém uma URL, os resultados retornados 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 próxima página dos resultados, envie uma solicitação GET para a URL na propriedade nextLink. A URL inclui um token de continuação para indicar onde você está nos resultados. Continue enviando solicitações para a URL nextLink até que ela não contenha mais uma URL nos resultados retornados.

Resiliência de APIs do Azure

As APIs REST do Azure foram projetadas para resiliência e disponibilidade contínua. As operações do painel de controle (solicitações enviadas para management.azure.com) na API REST são:

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

• Distribuídas entre Zonas de Disponibilidade (e também regiões) em locais que têm várias Zonas de Disponibilidade.

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

• Nunca são desativadas para atividades de manutenção.

Conteúdo relacionado

É isso. Depois de registrar seu aplicativo Microsoft Entra e ter uma técnica modular para adquirir um token de acesso e lidar com solicitações HTTP, é bastante fácil replicar seu código para aproveitar as novas APIs REST. Para obter mais informações sobre o registro de aplicativo e o modelo de programação Microsoft Entra, consulte a documentação do plataforma de identidade da Microsoft.

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

• Fiddler. O Fiddler é um proxy Web de depuração gratuito que pode interceptar as solicitações REST, facilitando o diagnóstico de mensagens de solicitação/resposta HTTP.
• JWT.ms, o que torna mais rápido e fácil despejar as declarações em seu token de portador para que você possa validar seu conteúdo.