Share via

Referência à API REST do Azure

  • Artigo

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

As APIs de Transferência de Estado De Representação (REST) são pontos finais de serviço que suportam conjuntos de operações HTTP (métodos), que fornecem acesso de criação/obtenção/atualização/eliminação aos recursos do serviço. As secções abaixo irão guiá-lo através de:

  • Os componentes básicos de um par de pedidos/respostas da API REST
  • Como registar a aplicação cliente no Azure Active Directory (Azure AD) para proteger os seus pedidos REST
  • Descrição geral da criação e envio de um pedido REST e processamento da resposta

Nota

A maioria das APIs REST do serviço do Azure tem uma biblioteca de SDK de cliente correspondente, que processa grande parte do código de cliente por si. Veja:

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

Componentes de um pedido/resposta da API REST

Um par de pedidos/respostas da API REST pode ser separado em 5 componentes:

  1. O URI do pedido, que consiste em: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Tenha em atenção que estamos a chamar isto separadamente aqui, uma vez que a maioria dos idiomas/arquiteturas exige que transmita isto separadamente da mensagem de pedido, mas na verdade está incluído no cabeçalho da mensagem de pedido.
    • Esquema URI: indica o protocolo utilizado para transmitir o pedido. Por exemplo, http ou https.
    • Anfitrião URI: o nome de domínio ou endereço IP do servidor onde o ponto final do serviço REST está alojado, como graph.microsoft.com
    • Caminho do recurso: 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 (opcional): utilizada 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 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 codificados com MIME transmitidos como parâmetros complexos. O tipo de codificação MIME para o corpo também deve ser especificado no cabeçalho do Content-type pedido, para operações POST/PUT. Tenha em atenção que alguns serviços exigem que utilize um tipo de 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 códigos de êxito 2xx e códigos de erro 4xx/5xx. 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 Content-type resposta.
  5. Campos do corpo da mensagem de resposta HTTP opcional
    • Os objetos de resposta codificados pelo MIME podem ser devolvidos no corpo de resposta HTTP, como uma resposta de um método GET que está a devolver dados. Normalmente, estes serão devolvidos num formato estruturado como JSON ou XML, conforme indicado pelo cabeçalho de Content-type resposta. Por exemplo, ao pedir um token de acesso de Azure AD, este será 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 será incluído um cabeçalho de resposta de Content-Type: application/json .

Registar a aplicação cliente no Azure AD

A maioria dos serviços do Azure (como os fornecedores de Resource Manager do Azure e as APIs clássicas de Gestão de Serviços) exige que o código do 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 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 todos os 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 Azure AD integrada ou já registou o cliente, pode avançar para a secção Criar o pedido.

Pré-requisitos

A sua aplicação cliente tem de dar a conhecer a sua configuração de identidade para Azure AD antes do tempo de execução, ao registá-la num inquilino Azure AD. Segue-se uma lista de itens a considerar antes de registar o cliente com Azure AD:

  • Se ainda não tiver um inquilino Azure AD, veja Como obter um inquilino do Azure Active Directory.
  • De acordo com o OAuth2 Authorization Framework, Azure AD suporta dois tipos de clientes. Compreender cada um irá ajudá-lo a decidir qual é o mais adequado para o seu cenário:
    • Os clientes web/confidenciais (executados num servidor Web) podem aceder aos recursos sob a sua própria identidade (ou seja, serviço/daemon) ou obter autorização delegada para aceder a recursos sob a identidade do utilizador com sessão iniciada (ou seja, aplicação Web). Apenas um cliente Web tem a capacidade de manter e apresentar de forma segura as suas próprias credenciais durante Azure AD autenticação para adquirir um token de acesso.
    • Os clientes nativos/públicos (instalados/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 irá criar dois objetos relacionados no inquilino Azure AD 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 Azure Active Directory.

Agora, estamos prontos para registar a sua aplicação cliente com Azure AD.

Registo de cliente

Para registar um cliente que aceda a uma API REST do Azure Resource Manager, veja Utilizar o portal para criar uma aplicação do Active Directory e um principal de serviço que possa aceder aos recursos para obter instruções de registo passo a passo. Este artigo (também disponível nas versões do PowerShell e da CLI para automatizar o registo) irá mostrar-lhe como:

  • registar a aplicação cliente com Azure AD
  • definir pedidos de permissão para permitir que o cliente aceda à API do Azure Resource Manager
  • configurar as definições de Controlo de Acesso Baseado em Funções (RBAC) do Azure Resource Manager para autorizar o cliente

Para todos os outros clientes, veja Integrar aplicações com o Azure Active Directory. Este artigo irá mostrar-lhe como:

  • registar a aplicação cliente com Azure AD, na secção "Adicionar uma aplicação"
  • criar uma chave secreta (se estiver a registar um cliente Web), na secção "Atualizar uma aplicação"
  • adicionar pedidos de permissão conforme exigido pela API, na secção "Atualizar uma aplicação"

Agora que concluiu o registo da sua aplicação cliente, podemos mudar para o seu código de cliente, onde irá criar o pedido REST e processar a resposta.

Criar o pedido

Esta secção abrange os primeiros 3 dos 5 componentes que abordámos anteriormente. Primeiro, temos de adquirir o token de acesso do Azure AD, que iremos utilizar na montagem do nosso cabeçalho de mensagem de pedido.

Adquirir um token de acesso

Assim que tiver um registo de cliente válido, existem essencialmente duas formas de integrar com Azure AD para adquirir um token de acesso:

  • Azure AD pontos finais de serviço OAuth2 neutros em linguagem/plataforma, que é o que vamos utilizar. Tal como os pontos finais da API REST do Azure que está a utilizar, as instruções fornecidas nesta secção não fazem suposições sobre a plataforma ou o idioma/script do cliente ao utilizar os pontos finais de Azure AD; apenas que podem enviar/receber pedidos HTTPS de/para Azure AD e analisar a mensagem de resposta.
  • As Bibliotecas de Autenticação da Microsoft (MSAL) específicas da plataforma/idioma. As bibliotecas fornecem wrappers assíncronos para os pedidos de ponto final do 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 detalhes, incluindo documentação de referência, transferências de bibliotecas e código de exemplo, consulte Bibliotecas de Autenticação da Microsoft.

Os dois pontos finais Azure AD que irá utilizar 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 irá depender 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, vamos assumir que o seu cliente irá utilizar um dos seguintes fluxos de concessão de autorização: código de autorização ou credenciais de cliente. Siga as instruções para o que melhor corresponde ao seu cenário, para adquirir o token de acesso que irá utilizar nas secções restantes.

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

Esta concessão pode ser utilizada por clientes web e nativos e requer 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 terá de pedir um código de autorização ao Azure AD. Veja Pedir um código de autorização para obter detalhes sobre o formato do pedido HTTPS GET para o /authorize ponto final e mensagens de pedido/resposta de exemplo. O URI irá conter parâmetros de cadeia de consulta, incluindo os seguintes que são específicos da sua aplicação cliente:

    • client_id - também conhecido como ID da aplicação, este é o GUID atribuído à sua aplicação cliente quando se registou na secção acima

    • redirect_uri - uma versão codificada por URL de [um dos] URIs de resposta/redirecionamento especificados durante o registo da sua aplicação cliente. Tenha em atenção que o valor que transmite tem de corresponder exatamente ao seu 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 da aplicação na respetiva configuração. Por exemplo:

      • Utilização de APIs do fornecedor de Resource Manager (e gestão de serviços clássica) do Azurehttps://management.core.windows.net/
      • Para outros recursos, veja a documentação da API ou a configuração da aplicação de recursos no portal do Azure. Veja também a identifierUris propriedade do objeto da aplicação Azure AD para obter mais detalhes.

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

  2. Em seguida, o cliente terá de resgatar o código de autorização de um token de acesso. Veja Utilizar o código de autorização para pedir um token de acesso para obter detalhes sobre o formato do pedido HTTPS POST para o /token ponto final e mensagens de pedido/resposta de exemplo. Uma vez que se trata de um pedido POST, desta vez irá empacotar os parâmetros específicos da aplicação no corpo do pedido. Além de algumas das mencionadas acima (juntamente com outras novas), passará :

    • code - este é o parâmetro de consulta que irá conter o código de autorização que obteve no passo 1.
    • client_secret - só precisará deste parâmetro se o cliente estiver configurado como uma aplicação Web. Este é o mesmo valor secreto/chave que gerou anteriormente, no registo de cliente.

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

Esta concessão só pode ser utilizada por clientes Web, permitindo que a aplicação aceda diretamente aos recursos (sem delegação de utilizadores) com as credenciais do próprio cliente, que são fornecidas no momento do registo. Normalmente, é utilizado por clientes não interativos (sem IU) em execução como um daemon/serviço e requer apenas o /token ponto final para adquirir um token de acesso.

As interações cliente/recurso para esta concessão são muito semelhantes ao passo 2 da concessão do código de autorização. Veja a secção "Pedir um Token de Acesso" nas chamadas serviço a serviço com credenciais de cliente para obter detalhes sobre o formato do pedido HTTPS POST para o /token ponto final e mensagens de pedido/resposta de exemplo.

Reunir a mensagem de pedido

Tenha em atenção que a maioria das linguagens/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/formatação do pedido, facilitando a escrita do código de cliente (ou seja, a classe HttpWebRequest no .NET Framework, por exemplo). Por questões de brevidade, apenas abordaremos os elementos importantes do pedido, dado que a maior parte deste procedimento será processada por si.

URI do pedido

Todos os pedidos REST protegidos requerem o protocolo HTTPS para o esquema URI, fornecendo o pedido e a resposta com um canal seguro, devido ao facto de as informações confidenciais serem transmitidas/recebidas. Estas informações (ou seja, o código de autorização Azure AD, token de acesso/portador, dados confidenciais de pedido/resposta) são encriptadas por uma camada de transporte inferior, garantindo a privacidade das mensagens.

O restante URI do pedido do serviço (o anfitrião, o caminho do recurso e quaisquer parâmetros de cadeia de consulta necessários) será determinado pela especificação da API REST relacionada. Por exemplo, as APIs do fornecedor de Resource Manager do Azure utilizam https://management.azure.com/, as APIs clássicas de Gestão de Serviços do Azure utilizam https://management.core.windows.net/, ambas requerem um api-version parâmetro de cadeia de consulta, etc.

Cabeçalho do pedido

O URI do pedido será agrupado no cabeçalho da mensagem de pedido, juntamente com quaisquer campos adicionais, conforme determinado pela especificação da API REST do seu serviço e pela especificação HTTP. Seguem-se alguns campos de cabeçalho comuns que poderá precisar no seu pedido:

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

Corpo do pedido

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

O corpo do pedido é 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 apresentado da seguinte forma:

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

Enviar o pedido

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

Por exemplo, um método de pedido GET HTTPS para um fornecedor de Resource Manager do Azure pode ser enviado com campos de cabeçalho de pedido semelhantes aos seguintes, mas repare 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, um método de pedido HTTPS PUT para um fornecedor de Resource Manager do Azure pode ser enviado com campos de corpo e cabeçalho de pedido 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 o pedido, o cabeçalho da mensagem de resposta e o corpo opcional serão devolvidos.

Processar a mensagem de resposta

Agora vamos terminar com os últimos 2 dos 5 componentes.

Para processar a resposta, terá de analisar o cabeçalho de resposta e, opcionalmente, o corpo da resposta (dependendo do pedido). No exemplo HTTPS GET indicado acima, utilizámos 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, 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, que contém a lista de subscrições do Azure e as respetivas 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 a 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 recentemente adicionado codificado no formato JSON, semelhante a:

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

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

Já está! Assim que tiver a sua aplicação Azure AD registada e uma técnica componente para adquirir um token de acesso e criar e processar pedidos HTTP, é bastante fácil replicar o código para tirar partido das novas APIs REST.

Conteúdo relacionado

  • Veja plataforma de identidades da Microsoft (Azure Active Directory para programadores) para obter mais informações sobre o registo de aplicações e o modelo de programação Azure AD, incluindo um índice abrangente de artigos de HowTo e QuickStart e código de exemplo.
  • Para testar pedidos/respostas HTTP, consulte
    • Fiddler. O Fiddler é um proxy de depuração web gratuito que pode intercetar os seus pedidos REST, facilitando o diagnóstico do pedido HTTP e das mensagens de resposta.
    • O Descodificador JWT e JWT.io, o que torna mais rápido e fácil a captura das afirmações no seu token de portador para que possa validar os respetivos conteúdos.

Utilize a secção comentários do LiveFyre que se segue a este artigo para fornecer feedback e ajudar-nos a refinar e moldar os nossos conteúdos.