Como enviar solicitações para as APIs do Azure Digital Twins usando o Postman

  • Artigo

Postman é uma ferramenta de teste REST que fornece funcionalidades chave de solicitação HTTP em uma GUI baseada em desktop e plugin. Você pode usá-lo para criar solicitações HTTP e enviá-las para as APIs REST do Azure Digital Twins. Este artigo descreve como configurar o cliente REST do Postman para interagir com as APIs do Azure Digital Twins. 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 você usará para fazer solicitações de API no Postman.
  2. Configure uma coleção Postman e configure o cliente Postman REST para usar seu token de portador para autenticar. Ao configurar a coleção, você pode escolher uma destas opções:
    1. Importe uma coleção pré-criada de solicitações de API do Azure Digital Twins.
    2. Crie a sua própria coleção a partir do zero.
  3. Adicione solicitações à sua coleção configurada e envie-as para as APIs do Azure Digital Twins.

O Azure Digital Twins tem 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 APIs, consulte APIs e SDKs do Azure Digital Twins. Este artigo contém informações para ambos os conjuntos de API.

Pré-requisitos

Para continuar usando o Postman para acessar as APIs do Azure Digital Twins, você precisa configurar uma instância do Azure Digital Twins e baixar o Postman. O restante desta seção orienta você por essas etapas.

Configurar a instância do Azure Digital Twins

Para trabalhar com Gêmeos Digitais do Azure neste artigo, você precisará de uma instância de Gêmeos Digitais do Azure e as permissões necessárias para usá-la. Se você já tiver uma instância do Azure Digital Twins configurada, poderá usar essa instância e pular para a próxima seção. Caso contrário, siga as instruções em Configurar uma instância e autenticação. As instruções contêm informações para ajudá-lo a verificar se você concluiu cada etapa com êxito.

Depois de configurar sua instância, anote o nome do host da instância. Você pode encontrar o nome do host no portal do Azure.

Baixar Postman

Em seguida, faça o download da versão desktop do cliente Postman.

Obter token ao portador

Agora que você configurou o Postman e sua instância do Azure Digital Twins, precisará obter um token de portador que as solicitações do Postman possam usar para autorizar nas APIs do Azure Digital Twins.

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

Se você tiver uma CLI do Azure instalada localmente, poderá iniciar um prompt de comando em sua máquina para executar os seguintes comandos. Caso contrário, você pode abrir uma janela do Azure Cloud Shell em seu navegador e executar os comandos lá.

  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 Gêmeos Digitais do Azure. Neste comando, você passará a ID do recurso para o ponto de extremidade do serviço Gêmeos Digitais do Azure, 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 de plano de controle.

    Para obter um token para usar 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 do recurso para o ponto de extremidade do serviço Gêmeos Digitais do Azure.

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

    Nota

    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 diferente do Microsoft Entra da instância, precisará solicitar um token do locatário "home" da instância do Azure Digital Twins. Para obter mais informações sobre esse processo, consulte Escrever 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. Este valor é o seu valor simbólico que irá fornecer ao Postman para autorizar os seus pedidos.

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

Gorjeta

Este token é válido por pelo menos cinco minutos e no máximo 60 minutos. Se você ficar sem tempo alocado para o token atual, poderá repetir as etapas nesta seção para obter um novo.

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

Sobre as coleções Postman

Os pedidos no Postman são guardados em coleções (grupos de pedidos). Ao criar uma coleção para agrupar suas solicitações, você pode aplicar configurações comuns a muitas 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 Azure Digital Twins, já que você só precisa configurar esses detalhes uma vez para toda a coleção.

Ao trabalhar com os Gêmeos Digitais do Azure, você 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.

Como alternativa, 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 de que você precisa.

As seções a seguir descrevem ambos os processos. O resto do artigo tem lugar na sua aplicação Postman local, por isso vá em frente e abra a aplicação Postman no seu computador agora.

Importar coleção de APIs do Azure Digital Twins

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 de API populares do plano de dados do Azure Digital Twins contendo 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 digite o 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 sua visualização principal do Postman, na guia Coleções.

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

Gorjeta

Para importar o conjunto completo de chamadas de API para uma determinada versão das APIs do Azure Digital Twins (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 o plano de controle e APIs de plano de dados, consulte APIs e SDKs do Azure Digital Twins.

Em seguida, continue para a próxima seção para adicionar um token de portador à coleção para autorização e conectá-lo à sua instância de gêmeos digitais do Azure.

Configurar autorização

Em seguida, edite a coleção que você criou para configurar alguns detalhes de acesso. Realce a coleção que criou e selecione o ícone Ver mais ações para apresentar as 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 do token que você reuniu na seção Obter token de portador para usá-lo para todas as solicitações de API em sua coleção.

  1. Na caixa de diálogo de edição da sua coleção, certifique-se de que está no separador 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 o 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 Guardar.

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

    Gorjeta

    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 recursos do Azure Digital Twins 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 de sua instância do Azure Digital Twins), você pode armazenar o valor em uma variável que se aplica a cada solicitação na coleção. A coleção de 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 anfitrião da sua instância Azure Digital Twins. Você pode encontrar esse valor na página de visão geral da sua instância no Portal.
    subscriptionId Plano de controlo O seu ID de subscrição do Azure.
    digitalTwinInstance Plano de controlo O nome da sua instância do Azure Digital Twins.

    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 extras, preencha e salve esses valores também.

  4. Selecione Guardar.

Quando terminar as etapas acima, você terminará de configurar a coleção. Você pode fechar a guia de edição da coleção, se desejar.

Explorar pedidos

Em seguida, explore as solicitações dentro da coleção de API do Azure Digital Twins. Você pode expandir a coleção para exibir as solicitações pré-criadas (classificadas por categoria de operação).

Solicitações diferentes exigem informações diferentes sobre sua 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 do Azure Digital Twins.

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

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

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

  3. A captura de tela a seguir mostra a API DigitalTwinModels Add . 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.

Crie a sua própria coleção

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

Criar uma coleção do Postman

  1. Para criar uma coleção, selecione o botão Novo 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. Abre-se um separador. Preencha os dados da nova coleção. Selecione o ícone Editar ao lado do nome padrão da coleção (Nova coleção) para substituí-lo por sua própria escolha de nome.

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

Em seguida, continue para a próxima seção para adicionar um token de portador à coleção para autorização.

Configurar autorização

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

  1. Ainda na caixa de diálogo de edição da sua nova coleção, vá para 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.

Quando terminar as etapas acima, você terminará 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 sua vista principal do Carteiro, no separador Coleções.

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

Adicionar um pedido individual

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

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

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

    Escolha um tipo de Solicitação.

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

  2. Esta ação abre a janela SAVE REQUEST, onde pode introduzir um nome para o seu pedido, dar-lhe uma descrição opcional e escolher a coleção da qual 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 visualizar sua solicitação na coleção e selecioná-la para exibir seus detalhes editáveis.

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

Definir detalhes da solicitação

Para fazer uma solicitação do Postman para uma das APIs do Azure Digital Twins, você precisará da URL da API e de informações sobre os detalhes necessários. Você pode encontrar essas informações na documentação de referência da API REST do Azure Digital Twins.

Para prosseguir 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 o URL da solicitação e digite a partir da documentação de referência. Para a API de consulta, isso é POSThttps://digitaltwins-host-name/query?api-version=2020-10-31 no momento.

  2. Em Postman, defina o tipo para a solicitação e insira a URL da solicitação, preenchendo os espaços reservados na URL conforme necessário. Use o nome do host da sua instância na seção 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 mostrados para a solicitação na guia Params correspondem aos descritos na documentação de referência. Para esta solicitação no Postman, o parâmetro foi preenchido automaticamente quando o api-version URL da solicitação foi inserido na etapa anterior. Para a API de consulta, esse é o único parâmetro necessário, portanto, esta etapa está concluída.

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

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

  6. Verifique se o corpo mostrado para a solicitação na guia Corpo corresponde às necessidades descritas na documentação de referência. Para a API de consulta, um corpo JSON é necessário para fornecer o texto da consulta. Aqui está um corpo de exemplo 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 do Azure Digital Twins, consulte Consultar o gráfico gêmeo.

  7. Verifique a documentação de referência para quaisquer outros campos que possam ser necessários para o seu tipo de pedido. Para a API de consulta, todos os requisitos foram atendidos na solicitação do Postman, portanto, esta etapa está concluída.

  8. Utilize o botão Enviar para enviar o seu pedido concluído. Screenshot of Postman showing the details of the new request. The Send button is highlighted.

Após o envio do pedido, os detalhes da resposta aparecerão na janela do Carteiro abaixo do pedido. Você pode visualizar o código de status da resposta e qualquer corpo de texto.

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 com os dados de resposta esperados fornecidos na documentação de referência, para verificar o resultado ou saber mais sobre quaisquer erros que surjam.

Próximos passos

Para saber mais sobre as APIs do Digital Twins, leia APIs e SDKs do Azure Digital Twins ou veja a documentação de referência para as APIs REST.