Compartilhar via

Usar o Insomnia com a API Web do Dataverse

Você pode usar muitas ferramentas de cliente de API para autenticar em ambientes do Microsoft Dataverse e redigir e enviar solicitações de API Web. Essas ferramentas facilitam o aprendizado, o teste e a execução de consultas ad hoc usando a API Web do Dataverse.

Este artigo tem duas metas:

  1. Demonstre uma estratégia para autenticar e conectar ao Dataverse usando o cliente Insomnia API com uma ID de aplicativo (cliente) do Microsoft Entra fornecida pela Microsoft, pré-aprovada para todos os ambientes do Dataverse. Usando essa estratégia, você não precisa registrar um aplicativo para começar a usar a API Web do Dataverse.
  2. Apresente algumas operações básicas de dados que você pode executar usando a API Web do Dataverse no contexto do cliente de API Insomnia. Usando essa abordagem, você pode usar a Insomnia para continuar a experimentar e aprender sobre a Web API do Dataverse.

Observação

As instruções deste artigo representam a experiência fornecida pelo Insomnia no momento em que este artigo foi escrito. A experiência do usuário provavelmente muda ao longo do tempo e este artigo pode não representar a experiência atual. O artigo é atualizado somente quando ocorrem alterações que interrompem fundamentalmente as etapas descritas aqui. Saiba mais na documentação do Insomnia.

Privacidade

As solicitações enviadas usando as ferramentas de API do cliente contêm informações que podem ser confidenciais. Muitos desenvolvedores não querem carregar essas informações em um serviço de nuvem.

O Scratch Pad local do Insomnia não exige que você crie uma conta e não armazena informações sobre solicitações enviadas. As instruções fornecidas aqui descrevem apenas como usar o Scratch Pad local do Insomnia. Você pode optar por criar uma conta e usar todos os recursos de Insônia, se desejar. Se você quiser uma versão que não tenha opções para criar uma conta e se concentre na privacidade, consulte o Insomnium.

Outras opções

Você também pode usar o PowerShell com o Visual Studio Code para autenticar com a API Web do Dataverse como alternativa. Comece a usar a API Web com o PowerShell e o Visual Studio Code.

PowerShell com Visual Studio Code:

Instalar Insomnia

Consulte a documentação do Insomnia para as etapas de instalação do Insomnia. As instruções diferem para macOS, Windows e Linux.

Para o Windows, o instalador é um arquivo executável que você baixa e executa. Quando a instalação for concluída, você poderá ver opções diferentes. Essas opções não devem interferir nas instruções neste artigo, mas podem mudar. Quando este artigo foi escrito, o instalador apresenta estas opções:

  • Para a opção de habilitar recursos para sincronizar dados com a nuvem, escolha Continuar armazenando localmente no Cofre Local.

  • Para a opção de criar uma conta, escolha Usar o Scratch Pad local. Saiba mais sobre o Insomnia Scratch Pad.

    A caixa de diálogo Bem-vindo à Insônia, incluindo a opção Uso do Scratch Pad local.

Configurar o ambiente base

Use ambientes de insônia para armazenar variáveis de ambiente. Variáveis de ambiente são um objeto JSON que contém pares chave-valor de dados que você pode referenciar para muitas finalidades.

Você atribui o ambiente base a cada workspace. Você pode acessar as variáveis dentro dela em todo o workspace.

  1. Depois de abrir o Insomnia, selecione o ícone de engrenagem ao lado do ambiente base para abrir a caixa de diálogo Gerenciar Ambientes. Ou use o atalho de teclado Ctrl + E .

  2. Copie o seguinte JSON:

    {
   "url": "https://yourorg.api.crm.dynamics.com",
   "version": "9.2",
   "webapiurl": "{{ _.url }}/api/data/v{{ _.version }}/",
   "redirecturl": "https://localhost",
   "authurl": "https://login.microsoftonline.com/common/oauth2/authorize?resource={{ _.url }}",
   "clientid": "51f81489-12ee-4a9e-aaae-a2591f45987d"
}

  3. Cole o JSON no ambiente base.

  4. Edite o valor da url propriedade e substitua o https://yourorg.api.crm.dynamics.com valor para corresponder à URL do seu ambiente do Dataverse.

    Você pode encontrar o ponto de extremidade da API Web para seu ambiente usando as instruções em Exibir recursos do desenvolvedor. Remova /api/data/v9.2 da URL do ponto de extremidade da API Web. Essa URL deve terminar em dynamics.com.

    Você pode ver avisos de que as referências às variáveis _.url e _.version não são resolvidas de imediato, como o seguinte aviso:

    Captura de tela do ambiente base do Insomnia com avisos de variáveis não resolvidas.

    No entanto, depois de fechar a janela e reabri-la, você poderá ver que as variáveis agora são conhecidas e resolvidas.

    Captura de tela do ambiente base do Insomnia com valores das variáveis resolvidos.

Criar sub-ambientes (opcional)

Se você precisar apenas se conectar a um único ambiente do Dataverse, use o ambiente base. Se você precisar se conectar a vários ambientes, crie sub-ambientes para cada ambiente do Dataverse. Por exemplo, crie um subconjunto para seus ambientes de desenvolvimento e teste do Dataverse.

  1. Como você fez com o ambiente base, selecione o ícone de engrenagem ao lado do ambiente base para abrir a caixa de diálogo Gerenciar Ambientes . Ou use o atalho de teclado Ctrl + E .

  2. Selecione o ícone para criar um novo ambiente. Ambientes podem ser compartilhados ou privados. Escolha o ambiente privado.

  3. Clique duas vezes no nome do Novo Ambiente que você criou e renomeie-o como quiser. Você pode dar a ele o nome do ambiente do Dataverse ao qual deseja se conectar ou algo como ambiente de desenvolvimento.

  4. Copie o seguinte JSON:

    {
   "url": "https://yourdevorg.api.crm.dynamics.com"
}

  5. Cole o JSON no ambiente que você criou.

  6. Edite o valor da url propriedade para representar o ponto de extremidade da API Web para seu outro ambiente, assim como você fez para o ambiente base.

    Observação

    Você só precisa incluir a url propriedade no subambiente. Quando você seleciona o subambiente, este valor substitui o valor especificado no ambiente base url. Você também pode incluir qualquer uma das cinco outras propriedades, se desejar, mas o valor da url propriedade é o único que é diferente para cada ambiente do Dataverse.

Configurar solicitações

Depois de configurar seu ambiente base e quaisquer subconjuntos, você estará pronto para configurar uma solicitação.

  1. Selecione o botão Nova Solicitação HTTP ou use o atalho de teclado Ctrl+N .

  2. Após o método HTTP, que é GET por padrão, digite _. e aguarde um momento. A insônia mostra uma lista de variáveis disponíveis para escolher:

    Captura de tela do Insomnia mostrando a lista de variáveis de ambiente disponíveis para a URL.

  3. Escolha a _.webapiurl variável. O campo VISUALIZAÇÃO de URL mostra o valor usando o valor da url propriedade para o ambiente selecionado.

  4. Na guia Autenticação , use a lista suspensa para selecionar OAuth 2.0AUTH TYPE.

    Captura de tela do menu suspenso da guia Autenticação com o OAuth 2.0 selecionado como o tipo de autenticação.

  5. Edite a configuração de autenticação conforme mostrado na tabela a seguir, usando as variáveis de ambiente que você criou:

    Campo Valor
    TIPO DE GRANT Implícito
    URL DE AUTORIZAÇÃO _.authurl
    ID DO CLIENTE _.clientid
    URL DE REDIRECIONAMENTO _.redirecturl

  6. Selecione Enviar.

    Uma caixa de diálogo é aberta para inserir as credenciais do ambiente.

    Depois de inserir suas credenciais, você verá os resultados no painel Visualização com esta aparência:

    {
"@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata",
"value": [
   {
      "name": "aadusers",
      "kind": "EntitySet",
      "url": "aadusers"
   },
   {
      "name": "accounts",
      "kind": "EntitySet",
      "url": "accounts"
   },
   {
      "name": "aciviewmappers",
      "kind": "EntitySet",
      "url": "aciviewmappers"
   },
   {
      "name": "actioncards",
      "kind": "EntitySet",
      "url": "actioncards"
   },
   ...

    Esse resultado é o documento do serviço de API Web. Você exibe o documento de serviço enviando uma solicitação GET para a raiz da URL do serviço de API Web. Ele lista os nomes de conjunto de entidades para todas as tabelas em seu ambiente do Dataverse. Quando você pode ver o documento de serviço, você se autenticou com êxito no ambiente do Dataverse.

    Dica

    Essa é uma maneira conveniente de localizar ou verificar o nome do conjunto de entidades para uma tabela com a qual você está trabalhando.

Exibir o documento de $metadata do CSDL

A linguagem CSDL (Common Schema Definition Language) $metadata documento é a fonte da verdade para tudo relacionado à API Web. Referencie-o com frequência.

  1. Edite a URL acrescentando $metadata?annotations=true após a _.webapiurl variável. A URL deve ser:

    GET _.webapiurl$metadata?annotations=true

  2. Selecione Enviar.

No painel Visualização , você verá uma mensagem informando Resposta acima de 5 MB oculta por motivos de desempenho, com as opções para Salvar em Arquivo e Mostrar De Qualquer Maneira. O arquivo é grande, mas você pode visualizar sem problemas.

Localizar definições de tipos

O documento CSDL $metadata é grande. A visualização do Insomnia fornece uma ferramenta de filtragem de resposta no rodapé. Use consultas XPath para filtrar a resposta e encontrar o que você precisa. A tabela seguinte mostra alguns exemplos:

Localizar Consulta XPath
Todos os tipos de entidade //*[local-name() = 'EntityType']
A conta tipo de entidade //*[local-name() = 'EntityType'][@Name = 'account']
Todas as funções //*[local-name() = 'Function']
A função WhoAmI //*[local-name() = 'Function'][@Name = 'WhoAmI']
Todas as ações //*[local-name() = 'Action']
A ação CreateMultiple //*[local-name() = 'Action'][@Name = 'CreateMultiple']
Todos os tipos complexos //*[local-name() = 'ComplexType']
O tipo complexo WhoAmIResponse //*[local-name() = 'ComplexType'][@Name = 'WhoAmIResponse']
Todos os tipos de enumeração //*[local-name() = 'EnumType']
O tipo de enumeração AccessRights //*[local-name() = 'EnumType'][@Name = 'AccessRights']

Saiba mais sobre os tipos definidos no documento $metadata CSDL.

Enviar uma solicitação WhoAmI

Agora que você está autenticado, modifique sua solicitação para invocar a função WhoAmI. Como WhoAmI é uma função, use um GET método. Essa função não tem parâmetros, portanto, é fácil de usar. Saiba mais sobre como usar o Web API Functions.

  1. Edite a URL acrescentando WhoAmI após a _.webapiurl variável. A URL deve ser:

    GET _.webapiurl WhoAmI

  2. Definir cabeçalhos de solicitação.

    Conforme descrito em cabeçalhos HTTP, cada solicitação de API Web deve ter um conjunto específico de cabeçalhos de solicitação. Talvez seja necessário modificar valores de cabeçalho para comportamentos diferentes.

    Na guia Cabeçalhos , selecione o botão Adicionar para inserir cada um dos seguintes cabeçalhos comuns:

    Cabeçalho Valor
    Accept application/json
    OData-MaxVersion 4.0
    OData-Version 4.0
    If-None-Match null
    Prefer odata.include-annotations="*"

    Esses cabeçalhos não alteram o comportamento da função WhoAmI, mas é bom começar a adicioná-los no início.

  3. Selecione Enviar.

    No painel Visualização , você verá dados correspondentes ao tipo complexo WhoAmIResponse.

    {
   "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
   "BusinessUnitId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
   "UserId": "22cc22cc-dd33-ee44-ff55-66aa66aa66aa",
   "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}

Recuperar dados

Para usar o Insomnia para recuperar registros, defina o nome do conjunto de entidades para o recurso.

  1. Altere a URL para remover WhoAmI após a variável _.webapiurl. Substitua-o accountspelo nome do conjunto de entidades para o tipo de entidade da conta. A URL deve ser:

    GET _.webapiurl accounts

  2. Na guia Parâmetros , defina os parâmetros para sua consulta.

    Você pode adicionar parâmetros individualmente selecionando o botão Adicionar . Mas você também pode selecionar a opção Edição em Massa, o que pode ser mais fácil.

    1. Selecione a opção Edição em Lote.
    2. Copie os seguintes parâmetros:
    $top: 3
$select: name,revenue,address1_city
$expand: primarycontactid($select=fullname)
$filter: address1_city eq 'Redmond'

    Essa consulta retorna colunas selecionadas dos três principais registros de conta localizados na cidade de Redmond. Ele também inclui informações sobre qualquer contato relacionado especificado como o contato principal das contas.

    1. Cole os valores no campo PARÂMETROS DE CONSULTA .

      Sua consulta deve ter esta aparência:

      Captura de tela do Insomnia mostrando uma consulta configurada que recupera registros de conta do Dataverse.

  3. Selecione Enviar.

    No painel Visualização , você verá resultados como os seguintes:

    {
"@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#accounts(name,revenue,address1_city,primarycontactid(fullname))",
"@Microsoft.Dynamics.CRM.totalrecordcount": -1,
"@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
"@Microsoft.Dynamics.CRM.globalmetadataversion": "2341840",
"value": [
   {
      "@odata.etag": "W/\"2343103\"",
      "name": "City Power & Light (sample)",
      "revenue@OData.Community.Display.V1.FormattedValue": "$100,000.00",
      "revenue": 100000.0,
      "address1_city": "Redmond",
      "accountid": "01eaf28f-81e1-ee11-904d-000d3a3517c4",
      "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
      "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
      "address1_composite": "Redmond",
      "primarycontactid": {
      "fullname": "Scott Konersmann (sample)",
      "contactid": "15eaf28f-81e1-ee11-904d-000d3a3517c4"
      }
   },
   {
      "@odata.etag": "W/\"2343104\"",
      "name": "Contoso Pharmaceuticals (sample)",
      "revenue@OData.Community.Display.V1.FormattedValue": "$60,000.00",
      "revenue": 60000.0,
      "address1_city": "Redmond",
      "accountid": "03eaf28f-81e1-ee11-904d-000d3a3517c4",
      "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
      "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
      "address1_composite": "Redmond",
      "primarycontactid": {
      "fullname": "Robert Lyon (sample)",
      "contactid": "17eaf28f-81e1-ee11-904d-000d3a3517c4"
      }
   },
   {
      "@odata.etag": "W/\"2343106\"",
      "name": "A. Datum Corporation (sample)",
      "revenue@OData.Community.Display.V1.FormattedValue": "$10,000.00",
      "revenue": 10000.0,
      "address1_city": "Redmond",
      "accountid": "07eaf28f-81e1-ee11-904d-000d3a3517c4",
      "_transactioncurrencyid_value@OData.Community.Display.V1.FormattedValue": "US Dollar",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "transactioncurrencyid",
      "_transactioncurrencyid_value@Microsoft.Dynamics.CRM.lookuplogicalname": "transactioncurrency",
      "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
      "address1_composite": "Redmond",
      "primarycontactid": {
      "fullname": "Rene Valdes (sample)",
      "contactid": "1beaf28f-81e1-ee11-904d-000d3a3517c4"
      }
   }
]
}

    Observação

    Esses resultados incluem muitos valores de anotação , como @OData.Community.Display.V1.FormattedValue porque o cabeçalho de Prefer: odata.include-annotations="*" solicitação definido em Enviar uma solicitação WhoAmI está definido para retornar todas as anotações. Saiba como solicitar anotações específicas.

Saiba mais sobre como consultar dados.

Criar um registro

Usando o Insomnia, você pode definir várias solicitações que podem ser reutilizadas. Uma maneira fácil de criar uma nova solicitação que mantém as configurações que você tem é duplicar uma solicitação existente. Nesta etapa, duplique a solicitação definida na seção Recuperar dados e crie uma nova solicitação para criar um registro.

  1. A solicitação criada em Recuperar dados tem o nome padrão Nova Solicitação, a menos que você tenha alterado. Renomeie a solicitação Recuperar Contas.

  2. Ao passar o mouse sobre a solicitação Recuperar Contas , selecione o menu suspenso e selecione Duplicar.

    Captura de tela do menu suspenso com a opção Duplicar para uma solicitação no Insomnia.

  3. Na caixa de diálogo Solicitação Duplicada , defina o Novo Nome para Criar Conta.

  4. Na nova solicitação Criar Conta, altere o método HTTP de GET .POST A URL já está definida para usar o nome do accounts conjunto de entidades, portanto, você não precisa alterar mais nada aqui. A URL deve ser:

    POST _.webapiurl accounts

  5. Na guia Parâmetros , exclua todos os parâmetros porque eles não são usados para a operação de criação.

  6. Na guia Corpo, use a lista suspensa para selecionar JSON no grupo TEXT:

    Captura de tela da lista suspensa da guia Corpo com a seleção de JSON na seção de texto.

  7. Copie o seguinte JSON:

    {
   "name": "An Example Account record (sample)",
   "revenue": 10000.0,
   "address1_city": "Redmond"
}

  8. Cole o JSON no campo Corpo .

    Observação

    Antes de selecionar Enviar para criar o registro, examine os dados nas guias Auth e Cabeçalhos. Como você criou essa solicitação duplicando a solicitação Recuperar Contas , você reutiliza todas as informações configuradas anteriormente.

  9. Selecione Enviar para criar o registro.

    Você verá que o serviço retornou 204 Sem Conteúdo, portanto, não há conteúdo para ver no painel Visualização .

    A URL do registro que foi criado está visível na lista Cabeçalhos. Procure o cabeçalho de resposta odata-entityid. O valor deve ser semelhante a este:

    https://yourorg.api.crm.dynamics.com/api/data/v9.2/accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)

    Essa URL contém o valor do campo de chave primária para o registro criado, nesse caso, o valor da accountid propriedade.

Saiba mais sobre como criar registros

Recuperar um registro

Depois de criar um registro de conta e obter o valor do campo de chave primária, use esse valor para recuperar o registro. Comece duplicando a solicitação Recuperar Contas .

  1. Duplicar a solicitação Recuperar Contas .

  2. Nomeie-a como Recuperar conta.

  3. Edite a URL para acrescentar o accountid valor entre parênteses após o nome do conjunto de entidades. Se a accountid conta que você criou em Criar um registro foi 5b4ced1c-88e1-ee11-904c-6045bd05e9d4, edite a URL para ser:

    GET _.webapiurl accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)

  4. Na guia Parâmetros , remova os $topparâmetros , $expande $filter , deixando apenas o $select parâmetro para limitar o número de colunas retornadas.

  5. Na guia Cabeçalhos , marque a caixa de seleção ao lado do Prefer cabeçalho para desabilitá-la para que nenhuma anotação seja retornada.

  6. Selecione Enviar.

    A resposta retorna 200 OK e o painel Visualização contém dados como o seguinte:

    {
   "@odata.context": "https://yourorg.api.crm.dynamics.com/api/data/v9.2/$metadata#accounts(name,revenue,address1_city)/$entity",
   "@odata.etag": "W/\"2343128\"",
   "name": "An Example Account record (sample)",
   "revenue": 10000.0000000000,
   "address1_city": "Redmond",
   "accountid": "5b4ced1c-88e1-ee11-904c-6045bd05e9d4",
   "_transactioncurrencyid_value": "57f82f38-09c8-ee11-907a-00224803d046",
   "address1_composite": "Redmond"
}

Saiba mais sobre como recuperar registros

Excluir um registro

Depois de criar e recuperar um registro usando o valor da chave primária, você pode excluí-lo.

  1. Duplicar a solicitação recuperar conta . Nomeie a nova solicitação Excluir conta.

  2. Altere o método HTTP de GET para DELETE.

    A URL ainda deve conter os dados com o accountid registro que você criou e recuperou antes:

    DELETE _.webapiurl accounts(5b4ced1c-88e1-ee11-904c-6045bd05e9d4)

  3. Na guia Parâmetros , remova o $select parâmetro porque ele não tem sentido para uma operação de exclusão.

  4. Selecione Enviar.

    Você verá que o serviço retornou 204 Sem Conteúdo, portanto, não há conteúdo para ver no painel Visualização .

  5. Tente enviar a solicitação recuperar conta agora. Ele retorna 404 Não Encontrado e o painel Visualização mostra este erro:

    {
   "error": {
      "code": "0x80040217",
      "message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist"
   }
}

  6. Habilite novamente o Prefer cabeçalho para a solicitação recuperar conta para que todas as anotações sejam retornadas.

  7. Envie a solicitação novamente. Agora você pode ver que muitas anotações são retornadas com a resposta 404 Não Encontrada :

    {
   "error": {
      "code": "0x80040217",
      "message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionSourceKey": "Plugin/Microsoft.Crm.Common.ObjectModel.AccountService",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiStepKey": "81cbbb1b-ea3e-db11-86a7-000a3a5473e8",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiDepthKey": "1",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiActivityIdKey": "ef7da2d8-c3bc-40f3-b67f-9d2981341086",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiPluginSolutionNameKey": "System",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiStepSolutionNameKey": "System",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionCategory": "ClientError",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionMessageName": "ObjectDoesNotExist",
      "@Microsoft.PowerApps.CDS.ErrorDetails.ApiExceptionHttpStatusCode": "404",
      "@Microsoft.PowerApps.CDS.HelpLink": "http://go.microsoft.com/fwlink/?LinkID=398563&error=Microsoft.Crm.CrmException%3a80040217&client=platform",
      "@Microsoft.PowerApps.CDS.InnerError.Message": "Entity 'account' With Id = 5b4ced1c-88e1-ee11-904c-6045bd05e9d4 Does Not Exist"
   }
}

    Esses detalhes não são úteis nesse contexto, porque o problema é óbvio. Mas esses detalhes podem ser úteis em outros cenários. Saiba mais sobre como incluir mais detalhes relacionados aos erros.

Saiba mais sobre como excluir registros.

Próximas Etapas 

Para saber mais sobre o que você pode fazer com a API Web do Dataverse, confira os seguintes artigos:

Saiba mais sobre tipos e operações de API Web

Executar operações usando a API Web

  • Last updated on