Partilhar via

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 um desktop e GUI baseado em 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.

    Captura de tela do console mostrando o resultado do comando az account get-access-token. O campo accessToken com seu valor de amostra realçado.

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 de plano de dados populares do Azure Digital Twins contendo dados de solicitação de exemplo.

  1. Na janela principal do Postman, selecione o botão Importar . Captura de tela de uma janela do Postman recém-aberta. O botão 'Importar' está realçado.

  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.

    Captura de ecrã da janela 'Importar' do Postman, mostrando o ficheiro a importar como uma coleção e o botão Importar.

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

Screenshot da janela principal do Postman. A coleção recém-importada é destacada na guia 'Coleções'.

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 opções de ação. Selecione Editar.

Screenshot de Carteiro. O ícone 'Ver mais ações' para a coleção importada é realçado e 'Editar' é realçado nas opções.

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 ao 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 .

    Captura de ecrã da caixa de diálogo de edição da coleção importada no Postman, mostrando o separador 'Autorização'.

  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.

    Captura de tela da caixa de diálogo de edição do Postman para a coleção importada, na guia 'Autorização'. O tipo é 'OAuth 2.0' e a caixa Token de acesso está realçada.

    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 da 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 Description
    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.

    Captura de ecrã da caixa de diálogo de edição da coleção importada no Postman, mostrando o separador 'Variáveis'. O campo 'VALOR ATUAL' é realçado.

  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 de Carteiro. A coleção é expandida para mostrar a guia do corpo de uma solicitação.

  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 da janela principal do Postman. O botão 'Novo' está realçado.

    Escolha um tipo de Coleção.

    Captura de ecrã da caixa de diálogo 'Criar Novo' no Postman. A opção 'Coleção' é destacada.

  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.

    Captura de tela da caixa de diálogo de edição da nova coleção no Postman. O ícone Editar ao lado do nome 'Nova coleção' é realçado.

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 ao 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 .

    Captura de ecrã da caixa de diálogo de edição da nova coleção no Postman, mostrando o separador 'Autorização'.

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

    Captura de ecrã da caixa de diálogo de edição do Postman para a nova coleção, no separador 'Autorização'. O tipo é 'OAuth 2.0' e a caixa Token de acesso está realçada.

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 da janela principal do Postman. A coleção personalizada recém-criada é realçada na guia 'Coleções'.

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 da janela principal do Postman. O botão 'Novo' está realçado.

    Escolha um tipo de Solicitação.

    Captura de ecrã da caixa de diálogo 'Criar Novo' no Postman. A opção 'Pedido' está realçada.

  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.

Captura de ecrã da janela 'Guardar pedido' no Postman mostrando os campos descritos. O botão 'Salvar na coleção de Gêmeos Digitais do Azure' está realçado.

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

Screenshot de Carteiro. A coleção de Gêmeos Digitais do Azure é expandida para mostrar os detalhes da solicitação.

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 quais detalhes ela exige. 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 é atualmente POST https://digitaltwins-host-name/query?api-version=2020-10-31.

  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.

    Captura de ecrã dos detalhes do novo pedido no Postman. O URL de consulta da documentação de referência foi preenchido na caixa URL do pedido.

  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 api-version automaticamente quando o 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:

    Captura de ecrã dos detalhes do novo pedido no Postman, no separador Corpo. Ele contém um corpo JSON bruto com uma consulta de 'SELECT * FROM DIGITALTWINS'.

    Para obter mais informações sobre como criar consultas do Azure Digital Twins, consulte Consultar o gráfico de gêmeos.

  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. Captura de tela do carteiro mostrando os detalhes do novo pedido. O botão Enviar está realçado.

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.

Captura de ecrã do pedido enviado no Postman. Abaixo dos detalhes da solicitação, a resposta é mostrada. O status é 200 OK e o corpo mostra os resultados da consulta.

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.