Como enviar solicitações às APIs dos Gêmeos Digitais do Azure usando o Postman

  • Artigo

O Postman é uma ferramenta de testes REST que fornece importantes funcionalidades de solicitação HTTP em uma GUI baseada em plug-in e desktop. Você pode usá-lo para criar solicitações HTTP e enviá-las às APIs REST dos Gêmeos Digitais do Azure. Este artigo descreve como configurar o cliente REST do Postman para interagir com as APIs dos Gêmeos Digitais do Azure. Essas informações são específicas do serviço Gêmeos Digitais do Azure.

Este artigo contém informações sobre as seguintes etapas:

  1. Use a CLI do Azure para obter um token de portador que será usado para fazer solicitações de API no Postman.
  2. Configure uma coleção do Postman e configure o cliente REST do Postman para usar o token de portador para fazer a autenticação. Ao configurar a coleção, você pode escolher uma destas opções:
    1. Importar uma coleção pré-criada de solicitações de APIs dos Gêmeos Digitais do Azure.
    2. Criar uma coleção própria do zero.
  3. Adicionar solicitações à sua coleção configurada, depois enviá-las às APIs dos Gêmeos Digitais do Azure.

Os Gêmeos Digitais do Azure têm dois conjuntos de APIs com os quais você pode trabalhar: plano de dados e plano de controle. Para saber mais sobre a diferença entre esses conjuntos de API, confira APIs e SDKs dos Gêmeos Digitais do Azure. Este artigo contém informações para os dois conjuntos de API.

Pré-requisitos

Para continuar o Postman para acessar as APIs dos Gêmeos Digitais, você precisa configurar uma instância dos Gêmeos Digitais do Azure e fazer o download do Postman. O restante desta seção orientará você nessas etapas.

Configurar instância dos Gêmeos Digitais do Azure

Para trabalhar com os Gêmeos Digitais do Azure neste artigo, você precisará ter uma instância dos Gêmeos Digitais do Azure e as permissões necessárias para usá-la. Se você já tiver uma instância dos Gêmeos Digitais do Azure configurada, use essa instância e vá direto para a próxima seção. Caso contrário, siga as instruções descritas em Configurar uma instância e uma autenticação. As instruções contêm informações que ajudarão você a verificar se cada etapa foi concluída com êxito.

Após configurar a instância, anote o nome do host da instância. Encontre o nome do host no portal do Azure.

Fazer o download do Postman

Depois baixe a versão para desktop do cliente Postman.

Obter o token de portador

Agora que você configurou o Postman e a instância dos Gêmeos Digitais do Azure, você precisa obter um token de portador que pode ser usado pelas solicitações do Postman para autorizar nas APIs dos Gêmeos Digitais do Azure.

Há várias maneiras de obter esse token. Este artigo usa a CLI do Azure para entrar em sua conta do Azure e obter um token.

Caso tenha uma CLI do Azure instalada localmente, será possível iniciar um prompt de comando em seu computador para executar os comandos a seguir. Caso contrário, você pode abrir uma janela de Azure Cloud Shell no navegador e executar os comandos por ali.

  1. Primeiro, verifique se você está conectado ao Azure com as credenciais apropriadas, executando este comando:

    az login

  2. Em seguida, use o comando az account get-access-token para obter um token de portador com acesso ao serviço dos Gêmeos Digitais do Azure. Neste comando, você passará a ID do recurso para o ponto de extremidade de serviço dos Gêmeos Digitais para obter um token de acesso que possa acessar os recursos dos Gêmeos Digitais do Azure.

    O contexto necessário para o token depende de qual conjunto de APIs você está usando, portanto, use as guias a seguir para selecionar entre APIs de plano de dados e plano de controle.

    Para obter um token a ser usado com as APIs do plano de dados, use o seguinte valor estático para o contexto do token: 0b07f429-9f4b-4714-9392-cc5e8e80c8b0. Esse valor é a ID de recurso para o ponto de extremidade de serviço dos Gêmeos Digitais do Azure.

    az account get-access-token --resource 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

    Observação

    Se você precisar acessar sua instância do Azure Digital Twins usando uma entidade de serviço ou conta de usuário que pertença a um locatário do Microsoft Entra diferente da instância, será necessário solicitar um token do locatário "home" da instância do Azure Digital Twins. Para obter mais informações sobre esse processo, confira Escrever um código de autenticação de aplicativo.

  3. Copie o valor de accessToken no resultado e salve-o para usar na próxima seção. Esse valor é o valor do token que você vai fornecer ao Postman para autorizar suas solicitações.

    Screenshot of the console showing the result of the az account get-access-token command. The accessToken field with its sample value highlighted.

Dica

Esse token é válido por um tempo mínimo de cinco minutos e um tempo máximo 60 de minutos. Se acabar o tempo alocado para o token atual, você pode repetir as etapas nesta seção para obter um novo.

Em seguida, você vai configurar o Postman para usar o token para fazer solicitações de API para os Gêmeos Digitais do Azure.

Sobre as coleções do Postman

As solicitações no postmaster são salvas em Coleções (grupos de solicitações). Ao criar uma coleção para agrupar suas solicitações, você pode aplicar as configurações comuns a várias solicitações de uma só vez. As configurações comuns podem simplificar muito a autorização se você planeja criar mais de uma solicitação nas APIs do Gêmeos Digitais do Azure, pois você só precisa configurar esses detalhes uma vez para toda a coleção.

Quando você trabalha com os Gêmeos Digitais do Azure, pode começar importando uma coleção pré-criada de todas as solicitações dos Gêmeos Digitais do Azure. Talvez você queira importar essa coleção se estiver explorando as APIs e quiser configurar um projeto rapidamente com exemplos de solicitação.

Você também pode optar por começar do zero, criando sua própria coleção vazia e preenchendo-a com solicitações individuais que chamam apenas as APIs que você precisa.

As seções a seguir descrevem os dois processos. O restante do artigo utiliza o aplicativo local do Postman, então abra o aplicativo do Postman no seu computador agora.

Importar a coleção de APIs dos Gêmeos Digitais do Azure

Uma maneira rápida de começar a usar os Gêmeos Digitais do Azure no Postman é importar uma coleção pré-criada de solicitações para as APIs. Siga as etapas abaixo para importar uma coleção de solicitações populares de API de plano de dados do Azure Digital Twins que contêm dados de solicitação de exemplo.

  1. Na janela principal do Postman, selecione o botão Importar. Screenshot of a newly opened Postman window. The 'Import' button is highlighted.

  2. Na janela Importar a seguir, selecione Link e insira a seguinte URL: https://raw.githubusercontent.com/microsoft/azure-digital-twins-postman-samples/main/postman_collection.json. Em seguida, selecione Importar para confirmar.

    Screenshot of Postman's 'Import' window, showing the file to import as a collection and the Import button.

A coleção recém importada agora pode ser vista na exibição principal do Postman, na guia Coleções.

Screenshot of the main Postman window. The newly imported collection is highlighted in the 'Collections' tab.

Dica

Para importar o conjunto completo de chamadas de API para uma determinada versão das APIs do Gêmeos Digitais do Azure (incluindo plano de controle ou plano de dados), você também pode importar arquivos Swagger como coleções. Para obter links para os arquivos Swagger para as APIs do plano de controle e do plano de dados, consulte APIs e SDKs do Azure Digital Twins.

Continue na próxima seção para adicionar um token de portador à coleção para autorização e faça a conexão com a instância dos Gêmeos Digitais.

Configurar a autorização

Edite a coleção que você criou para configurar alguns detalhes de acesso. Realce a coleção que você criou e selecione o ícone Exibir mais ações para exibir opções de ação. Selecione Editar.

Screenshot of Postman. The 'View more actions' icon for the imported collection is highlighted, and 'Edit' is highlighted in the options.

Siga estas etapas para adicionar um token de portador à coleção para autorização. Use o valor de token que você coletou na seção Obter token de portador para todas as solicitações de API em sua coleção.

  1. Na caixa de diálogo de edição da coleção, certifique-se de que você está na guia Autorização.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Defina o Tipo como OAuth 2.0 e cole seu token de acesso na caixa Token de Acesso. Você deve usar o token correto para o tipo de API que está usando, pois há tokens diferentes para APIs de plano de dados versus APIs de plano de controle. Selecione Salvar.

    Screenshot of Postman edit dialog for the imported collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

    Dica

    Você pode optar por ativar o compartilhamento de token se quiser armazenar o token com a solicitação na nuvem do Postman e, potencialmente, compartilhar seu token com outras pessoas.

Outra configuração

Você pode ajudar a coleção a se conectar facilmente aos seus recursos de Gêmeos Digitais do Azure definindo algumas variáveis fornecidas com a coleção. Quando muitas solicitações em uma coleção exigem o mesmo valor (como o nome do host da instância dos Gêmeos Digitais), você pode armazenar o valor em uma variável que se aplica a todas as solicitações na coleção. A coleção Gêmeos Digitais do Azure vem com variáveis pré-criadas que você pode definir no nível da coleção.

  1. Ainda na caixa de diálogo de edição da sua coleção, vá para a guia Variáveis.

  2. Use a tabela a seguir para definir os valores das variáveis na coleção:

    Variável Conjunto de APIs Descrição
    digitaltwins-hostname Plano de dados o nome do host da instância dos Gêmeos Digitais do Azure. Você pode encontrar esse valor na página de visão geral de sua instância no Portal.
    subscriptionId Painel de controle Sua ID da assinatura do Azure.
    digitalTwinInstance Painel de controle O nome da instância dos Gêmeos Digitais do Azure.

    Screenshot of the imported collection's edit dialog in Postman, showing the 'Variables' tab. The 'CURRENT VALUE' field is highlighted.

  3. Se sua coleção tiver variáveis adicionais, preencha e salve esses valores também.

  4. Selecione Salvar.

Ao concluir as etapas acima, você termina de configurar a coleção. Você pode fechar a guia de edição da coleção, se desejar.

Explorar as solicitações

Explore as solicitações na coleção de API do Gêmeos Digitais do Azure. Você pode expandir a coleção para exibir as solicitações criadas previamente (classificadas por categoria de operação).

Solicitações diferentes exigem informações diferentes sobre a instância e seus dados. Para ver todas as informações necessárias para criar uma solicitação específica, procure os detalhes da solicitação na documentação de referência da API REST dos Gêmeos Digitais do Azure.

Você pode editar os detalhes de uma solicitação na coleção do Postman seguindo estas etapas:

  1. Selecione-o na lista para abrir seus detalhes editáveis.

  2. A maioria das solicitações na coleção de amostra é pré-configurada para ser executada sem fazer mais alterações.

  3. A captura de tela a seguir mostra a API de adição do DigitalTwinModels. Na guia Corpo, você pode ver a carga JSON que define o novo modelo a ser adicionado:

  4. Preencha os valores para as variáveis listadas na guia Params em Variáveis de Caminho.

    Screenshot of Postman. The collection is expanded to show the body tab of a request.

  5. Para executar a solicitação, use o botão Enviar .

Você também pode adicionar suas próprias solicitações à coleção, usando o processo descrito na seção Adicionar uma solicitação individual.

Criar suas coleções

Em vez de importar a coleção existente de APIs de Gêmeos Digitais do Azure, você também pode criar sua própria coleção do zero. Você pode preenchê-la com solicitações individuais usando a documentação de referência da API REST dos Gêmeos Digitais do Azure.

Criar uma coleção Postman

  1. Para criar uma coleção, selecione o botão Nova na janela principal do Postman.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Escolha um tipo de Coleção.

    Screenshot of the 'Create New' dialog in Postman. The 'Collection' option is highlighted.

  2. Uma guia é aberta. Preencha os detalhes da nova coleção. Selecione o ícone de Edição ao lado do nome padrão da coleção (Nova Coleção) para substituí-lo pelo nome de sua escolha.

    Screenshot of the new collection's edit dialog in Postman. The Edit icon next to the name 'New Collection' is highlighted.

Continue na próxima seção para adicionar um token de portador à coleção para autorização.

Configurar a autorização

Siga estas etapas para adicionar um token de portador à coleção para autorização. Use o valor de token que você coletou na seção Obter token de portador para todas as solicitações de API em sua coleção.

  1. Ainda na caixa de diálogo de edição para sua nova coleção, acesse a guia Autorização.

    Screenshot of the new collection's edit dialog in Postman, showing the 'Authorization' tab.

  2. Defina o tipo como OAuth 2.0, cole o token de acesso na caixa Token de Acesso e selecione Salvar.

    Screenshot of the Postman edit dialog for the new collection, on the 'Authorization' tab. Type is 'OAuth 2.0', and Access Token box is highlighted.

Ao concluir as etapas acima, você termina de configurar a coleção. Você pode fechar a guia de edição da nova coleção, se desejar.

A nova coleção pode ser vista na exibição principal do Postman, na guia Coleções.

Screenshot of the main Postman window. The newly created custom collection is highlighted in the 'Collections' tab.

Adicionar uma solicitação individual

Agora que sua coleção está configurada, você pode adicionar suas próprias solicitações às APIs do Gêmeo Digital.

  1. Para criar uma solicitação, use novamente o botão Nova.

    Screenshot of the main Postman window. The 'New' button is highlighted.

    Escolher um tipo de Solicitação.

    Screenshot of the 'Create New' dialog in Postman. The 'Request' option is highlighted.

  2. Essa ação abre a janela SALVAR SOLICITAÇÃO, onde você pode inserir um nome para a solicitação, fornecer uma descrição opcional e escolher a coleção da qual ela faz parte. Preencha os detalhes e salve a solicitação na coleção que você criou anteriormente.

Screenshot of 'Save request' window in Postman showing the fields described. The 'Save to Azure Digital Twins collection' button is highlighted.

Agora você pode exibir sua solicitação na coleção e selecioná-la para abrir seus detalhes editáveis.

Screenshot of Postman. The Azure Digital Twins collection is expanded to show the request's details.

Definir os detalhes da solicitação

Para fazer uma solicitação no Postman para uma das APIs dos Gêmeos Digitais, você vai precisar da URL da API e das informações sobre os detalhes que ela exige. Você pode encontrar essas informações na documentação de referência da API REST dos Gêmeos Digitais do Azure.

Para continuar com uma consulta de exemplo, este artigo usará a API de Consulta de Gêmeos Digitais do Azure para consultar todos os gêmeos digitais em uma instância.

  1. Obtenha a URL e o tipo da solicitação na documentação de referência. No momento, POSThttps://digitaltwins-host-name/query?api-version=2020-10-31 são usados na API de Consulta.

  2. No Postman, defina o tipo e insira a URL da solicitação, preenchendo os espaços reservados na URL, conforme o necessário. Use o nome do host da instância da Seção de pré-requisitos.

    Screenshot of the new request's details in Postman. The query URL from the reference documentation has been filled into the request URL box.

  3. Verifique se os parâmetros exibidos para a solicitação na guia Params correspondem aos descritos na documentação de referência. Para essa solicitação no Postman, o parâmetro api-version foi preenchido automaticamente quando a URL de solicitação foi inserida na etapa anterior. Para a API de Consulta, esse é o único parâmetro necessário, portanto, essa etapa está concluída.

  4. Na guia Autorização, defina o Tipo como Herdar autenticação do pai. Isso indica que essa solicitação vai usar a autorização que você configurou anteriormente para toda a coleção.

  5. Verifique se os cabeçalhos exibidos para a solicitação na guia Cabeçalhos correspondem aos descritos na documentação de referência. Para essa solicitação, vários cabeçalhos foram preenchidos automaticamente. Para a API de Consulta, nenhuma das opções de cabeçalho é necessária, portanto, essa etapa está concluída.

  6. Verifique se o corpo exibido para a solicitação na guia Corpo corresponde ao descrito na documentação de referência. Para a API de Consulta, um corpo JSON é necessário para fornecer o texto da consulta. Veja um exemplo de corpo para essa solicitação que consulta todos os gêmeos digitais na instância:

    Screenshot of the new request's details in Postman, on the Body tab. It contains a raw JSON body with a query of 'SELECT * FROM DIGITALTWINS'.

    Para obter mais informações sobre como criar consultas dos Gêmeos Digitais do Azure, consulte Consultar o grafo gêmeo.

  7. Verifique a documentação de referência para todos os outros campos que podem ser necessários para o tipo da sua solicitação. Para a API de Consulta, todos os requisitos foram atendidos na solicitação do Postman, portanto, essa etapa está concluída.

  8. Use o botão Enviar para enviar a solicitação completa. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

Depois de enviar a solicitação, os detalhes da resposta serão exibidos na janela do Postman abaixo da solicitação. Você pode exibir o código de status da resposta e todo o texto do corpo.

Screenshot of the sent request in Postman. Below the request details, the response is shown. Status is 200 OK and body shows query results.

Você também pode comparar a resposta aos dados de resposta esperados fornecidos na documentação de referência para verificar o resultado ou saber mais sobre eventuais erros.

Próximas etapas

Para saber mais sobre as APIs dos Gêmeos Digitais, leia o artigo APIs e SDKs dos Gêmeos Digitais do Azure ou veja a documentação de referência das APIs REST.