Compartilhar via

Referência de API REST do Azure

  • Artigo

Bem-vindo à Referência da API REST do Azure.

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/exclusão aos recursos do serviço. As seções a seguir explicarão:

  • Os componentes básicos de um par de solicitação/resposta da API REST
  • Como registrar seu aplicativo cliente no Azure Active Directory (Azure AD) para proteger suas solicitações REST
  • Visões gerais sobre como criar e enviar uma solicitação REST e lidar com a resposta

Observação

A maioria das APIs REST do serviço do Azure tem uma biblioteca do SDK do cliente correspondente, que manipula grande parte do código do cliente para você. Consulte:

SDK do Azure .NET
SDK do Java do Azure
Azure CLI 2.0 SDK

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}. Observe que estamos chamando isso separadamente aqui, pois a maioria dos idiomas/estruturas exige que você passe isso separadamente da mensagem de solicitação, mas ela é realmente incluída no cabeçalho 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: o nome de domínio ou o endereço IP do servidor em que 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 caracteres de consulta (opcional): usada para fornecer parâmetros simples adicionais, como a versão da API, critérios de seleção de recursos etc.
  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 pelo 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 codificados em MIME passados como parâmetros complexos. O tipo de codificação MIME para o corpo também deve ser especificado no cabeçalho da Content-type solicitação para operações POST/PUT. Observe que alguns serviços exigem que você use um tipo MIME específico, como application/json.
  4. Campos de cabeçalho de mensagem de resposta HTTP
    • Um código http status, variando de códigos de êxito 2xx a códigos de erro 4xx/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 Content-type resposta.
  5. Campos opcionais do corpo da mensagem de resposta HTTP
    • Objetos de resposta codificados em MIME podem ser retornados no corpo da resposta HTTP, como uma resposta de um método GET que está retornando dados. Normalmente, eles serão retornados em um formato estruturado como JSON ou XML, conforme indicado pelo cabeçalho de Content-type resposta. Por exemplo, ao solicitar um token de acesso de Azure AD, ele será 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 será incluído.

Registre seu aplicativo cliente com o Azure AD

A maioria dos serviços do Azure (como provedores de Resource Manager do Azure e as APIs clássicas de Gerenciamento de Serviços) 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 Azure AD, que fornece ao cliente um token de acesso como prova da autenticação/autorização. Em seguida, o token é enviado para o serviço do Azure no cabeçalho autorização HTTP de todas as 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 Azure AD integrada ou já registrou seu cliente, pule para a seção Criar a solicitação.

Pré-requisitos

Seu aplicativo cliente deve tornar sua configuração de identidade conhecida por Azure AD antes do tempo de execução, registrando-a em um locatário Azure AD. Veja abaixo uma lista de itens a serem considerados antes de registrar seu cliente com Azure AD:

  • Se você ainda não tiver um locatário Azure AD, consulte Como obter um locatário do Azure Active Directory.
  • De acordo com a Estrutura de Autorização OAuth2, Azure AD dá suporte a dois tipos de clientes. Entender cada um ajudará você a decidir qual é o mais apropriado para seu cenário:
    • Clientes web/confidenciais (executados em um servidor Web) podem acessar recursos em sua própria identidade (ou seja: serviço/daemon) ou obter autorização delegada para acessar recursos sob a identidade do usuário conectado (ou seja: aplicativo Web). Somente um cliente Web tem a capacidade de manter e apresentar com segurança suas próprias credenciais durante Azure AD autenticação para adquirir um token de acesso.
    • clientes nativos/públicos (instalados/executados em um dispositivo) 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 criará dois objetos relacionados no locatário Azure AD 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, examine Objetos de aplicativo e entidade de serviço no Azure Active Directory.

Agora estamos prontos para registrar seu aplicativo cliente com Azure AD.

Registro do cliente

Para registrar um cliente que acessará uma API REST do Azure Resource Manager, confira Usar o portal para criar um aplicativo do Active Directory e uma entidade de serviço que possa acessar recursos para obter instruções de registro passo a passo. Este artigo (também disponível no PowerShell e versões da CLI para automatizar o registro) mostrará como:

  • registrar o aplicativo cliente com Azure AD
  • definir solicitações de permissão para permitir que o cliente acesse a API do Azure Resource Manager
  • definir as configurações de RBAC (Controle de Acesso Baseada em Função) do Resource Manager do Azure para autorizar o cliente

Para todos os outros clientes, consulte Integrando aplicativos com o Azure Active Directory. Esta artigo mostrará como:

  • registre o aplicativo cliente com Azure AD, na seção "Adicionando um aplicativo"
  • criar uma chave secreta (se você estiver registrando um cliente Web), na seção "Atualizando um aplicativo"
  • adicionar solicitações de permissão conforme exigido pela API, na seção "Atualizando um aplicativo"

Agora que você concluiu o registro do aplicativo cliente, podemos migrar para o código do cliente, no qual você criará a solicitação REST e manipulará a resposta.

Criar a solicitação

Esta seção aborda os três primeiros dos 5 componentes que discutimos anteriormente. Primeiro, precisamos adquirir o token de acesso do Azure AD, que usaremos na montagem do cabeçalho da mensagem de solicitação.

Adquirir um token de acesso

Depois de ter um registro de cliente válido, há essencialmente duas maneiras de integrar com Azure AD para adquirir um token de acesso:

  • pontos de extremidade de serviço OAuth2 de plataforma/idioma neutro do Azure AD, que é o que usaremos. Assim como os pontos de extremidade da API REST do Azure que você está usando, as instruções fornecidas nesta seção não fazem suposições sobre a plataforma ou o idioma/script do cliente ao usar os pontos de extremidade Azure AD; apenas que ele pode enviar/receber solicitações HTTPS de/para Azure AD e analisar a mensagem de resposta.
  • As MSAL (Bibliotecas de Autenticação da Microsoft) específicas da plataforma/idioma. As bibliotecas fornecem wrappers assíncronos para as solicitações de ponto de extremidade OAuth2 e recursos robustos de tratamento de token, como armazenamento em cache e gerenciamento de token de atualização. Para obter mais detalhes, incluindo documentação de referência, downloads de biblioteca e código de exemplo, consulte Bibliotecas de Autenticação da Microsoft.

Os dois pontos de extremidade Azure AD que você usará para autenticar seu cliente e adquirir um token de acesso são chamados de OAuth2 /authorize e /token pontos de extremidade. Como usá-los dependerá 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, vamos supor que seu cliente usará um dos seguintes fluxos de concessão de autorização: código de autorização ou credenciais de cliente. Siga as instruções para aquele que melhor corresponde ao seu cenário, para adquirir o token de acesso que você usará nas seções restantes.

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

Essa concessão pode ser usada por clientes Web e nativos e requer 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 precisará solicitar um código de autorização do Azure AD. Consulte Solicitar um código de autorização para obter detalhes sobre o formato da solicitação HTTPS GET para o /authorize ponto de extremidade e exemplo de mensagens de solicitação/resposta. O URI conterá parâmetros de cadeia de caracteres de consulta, incluindo os seguintes que são específicos para seu aplicativo cliente:

    • client_id - também conhecido como ID do aplicativo, esse é o GUID atribuído ao seu aplicativo cliente quando você se registrou na seção acima

    • redirect_uri – uma versão codificada em URL de [um dos] URIs de resposta/redirecionamento especificados durante o registro do aplicativo cliente. Observe que o valor que você passa deve corresponder exatamente ao seu registro!

    • resource – um URI do 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:

      • O provedor de Resource Manager do Azure (e as APIs clássicas de Gerenciamento de Serviços) usamhttps://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. Consulte também a identifierUris propriedade do objeto de aplicativo Azure AD para obter mais detalhes.

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

  2. Em seguida, seu cliente precisará resgatar o código de autorização para um token de acesso. Consulte Usar o código de autorização para solicitar um token de acesso para obter detalhes sobre o formato da solicitação HTTPS POST para o /token ponto de extremidade e exemplo de mensagens de solicitação/resposta. Como essa é uma solicitação POST, desta vez você empacotará os parâmetros específicos do aplicativo no corpo da solicitação. Além de alguns dos mencionados acima (juntamente com outros novos), você passará :

    • code - esse é o parâmetro de consulta que conterá o código de autorização obtido na etapa nº 1.
    • client_secret – você só precisará desse parâmetro se o cliente estiver configurado como um aplicativo Web. Esse é o mesmo valor de segredo/chave gerado anteriormente, no registro do cliente.

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

Essa concessão só pode ser usada por clientes Web, permitindo que o aplicativo acesse recursos diretamente (sem delegação de usuário) usando as próprias credenciais do cliente, que são fornecidas no momento do registro. Normalmente, ele é usado por clientes não interativos (sem interface do usuário) em execução como um daemon/serviço e requer apenas o /token ponto de extremidade para adquirir um token de acesso.

As interações cliente/recurso para essa concessão são muito semelhantes à etapa 2 da concessão de código de autorização. Consulte a seção "Solicitar um token de acesso" em Chamadas de serviço para serviço usando credenciais de cliente para obter detalhes sobre o formato da solicitação HTTPS POST para o /token ponto de extremidade e exemplo de mensagens de solicitação/resposta.

Montar a mensagem de solicitação

Observe que a maioria das linguagens de programação/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/formatação da solicitação, facilitando a gravação do código do cliente (ou seja, a classe HttpWebRequest no .NET Framework, por exemplo). Para resumir, abordaremos apenas os elementos importantes da solicitação, dado que a maior parte disso será tratada para você.

URI da solicitação

Todas as solicitações REST protegidas exigem o protocolo HTTPS para o esquema de URI, fornecendo a solicitação e a resposta com um canal seguro, devido ao fato de que informações confidenciais são transmitidas/recebidas. Essas informações (ou seja: o código de autorização Azure AD, o token de acesso/portador, 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) será determinado pela especificação da API REST relacionada. Por exemplo, as APIs do provedor de Resource Manager do Azure usam https://management.azure.com/, as APIs clássicas do Gerenciamento de Serviços do Azure usam https://management.core.windows.net/, ambas exigem um api-version parâmetro de cadeia de caracteres de consulta etc.

Cabeçalho da solicitação

O URI da solicitação será agrupado no cabeçalho da mensagem de solicitação, juntamente com quaisquer campos adicionais, conforme determinado pela especificação da API REST do serviço e pela especificação HTTP. Aqui estão alguns campos de cabeçalho comuns que você pode precisar em sua solicitação:

  • Authorization: contém o token de portador OAuth2 para proteger a solicitação, conforme adquirido anteriormente de Azure AD
  • Content-Type: normalmente definido como "application/json" (pares nome/valor no formato JSON) e especifica o tipo MIME do corpo da solicitação.
  • Host: esse é o nome de domínio ou 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, deve ser formatado 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/corpo da mensagem de solicitação relacionado, você está pronto para enviar a solicitação para o ponto de extremidade de serviço REST.

Por exemplo, um método de solicitação HTTPS GET para um provedor de Resource Manager do Azure pode ser enviado usando campos de cabeçalho de solicitação semelhantes aos seguintes, mas 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 um método de solicitação HTTPS PUT para um provedor de Resource Manager do Azure pode ser enviado usando campos de corpo e cabeçalho de solicitação semelhantes aos seguintes:

PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/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 serão retornados.

Processar a mensagem de resposta

Agora terminaremos com os dois últimos dos cinco componentes.

Para processar a resposta, você precisará analisar o cabeçalho de resposta e, opcionalmente, o corpo da resposta (dependendo da solicitação). No exemplo HTTPS GET fornecido acima, usamos o ponto de extremidade /subscriptions para recuperar a lista de assinaturas de um usuário. Supondo que a resposta tenha sido bem-sucedida, devemos receber campos de cabeçalho de resposta semelhantes aos seguintes:

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

e um corpo de resposta, contendo a lista de assinaturas do Azure e suas propriedades individuais codificadas no formato JSON, semelhante a:

{
    "value":[
        {
        "id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
        "subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
        "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, devemos receber um cabeçalho de resposta semelhante ao seguinte, confirmando que nossa operação PUT para adicionar o "ExampleResourceGroup" foi bem-sucedida:

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

e um corpo de resposta, confirmando o conteúdo do nosso grupo de recursos recém-adicionado codificado no formato JSON, semelhante a:

{
    "id":"/subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

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

É isso! Depois que você tiver seu aplicativo Azure AD registrado e uma técnica componente para adquirir um token de acesso e criar e processar solicitações HTTP, é bastante fácil replicar seu código para aproveitar as novas APIs REST.

Conteúdo relacionado

  • Consulte plataforma de identidade da Microsoft (Azure Active Directory para desenvolvedores) para obter mais informações sobre o registro de aplicativo e o modelo de programação Azure AD, incluindo um índice abrangente de artigos HowTo e QuickStart e código de exemplo.
  • Para testar solicitações/respostas HTTP, marcar
    • Fiddler. O Fiddler é um proxy de depuração da Web gratuito que pode interceptar suas solicitações REST, facilitando o diagnóstico das mensagens de solicitação e resposta HTTP.
    • O Decodificador JWT e JWT.io, o que torna rápido e fácil despejar as declarações em seu token de portador para que você possa validar seu conteúdo.

Use a seção de comentários do LiveFyre que segue este artigo para fornecer comentários e nos ajudar a refinar e moldar nosso conteúdo.