Recuperar e executar consultas predefinidas

Artigo
10/31/2017

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

O Microsoft Dynamics 365 oferece uma maneira para que os administradores criem exibições do sistema disponíveis para todos os usuários. Os usuários individuais podem salvar consultas de localização avançada para reutilização no aplicativo. Ambas representam consultas predefinidas que você pode recuperar e executar usando a API Web. Você também pode compor uma consulta usando o FetchXml e usá-la para recuperar dados.

Neste tópico

Consultas predefinidas

Usar FetchXML personalizado

Consultas predefinidas

O Microsoft Dynamics 365 permite que você defina, salve e execute dois tipos de consulta conforme listado abaixo.

Tipo de consulta	Descrição
Consulta Salva	Exibições definidas pelo sistema para uma entidade. Essas exibições são armazenadas no savedquery EntityType.Para obter mais informações:Personalizar modos de exibição de entidade
Consulta de Usuário	As pesquisas de Localização Avançada salvas pelos usuários para uma entidade. Essas exibições são armazenadas no userquery EntityType.Para obter mais informações:Entidade UserQuery (exibição salva)

Os registros dos dois tipos de entidades contêm a definição de FetchXML para os dados a serem retornados. Você pode consultar o tipo respectivo da entidade para recuperar o valor da chave primária. Com o valor da chave primária, você pode executar a consulta passando o valor da chave primária. Por exemplo, para executar a consulta Contas Ativas salva, primeiro você deve obter a chave primária usando uma consulta como essa.

GET cc_WebAPI_ServiceURI/savedqueries?$select=name,savedqueryid&$filter=name eq 'Active Accounts'

Em seguida, você pode usar o valor de savedqueryid e passá-lo como o valor do parâmetro savedQuery para o conjunto de entidades accounts.

GET cc_WebAPI_ServiceURI/accounts?savedQuery=00000000-0000-0000-00aa-000010001002

Use a mesma abordagem para obter o userqueryid e passá-lo como o valor do parâmetro userQuery para o conjunto de entidades que corresponde ao returnedtypecode correspondente da consulta salva.

GET cc_WebAPI_ServiceURI/accounts?userQuery=121c6fd8-1975-e511-80d4-00155d2a68d1

Aplicar uma consulta a qualquer coleção do tipo adequado

Além de simplesmente aplicar a consulta salva à coleção principal do conjunto de entidades, você também pode usar uma consulta salva ou uma consulta de usuário para aplicar a mesma filtragem a qualquer coleção do tipo adequado de entidades. Por exemplo, se você quiser aplicar uma consulta em relação apenas às entidades relacionadas a uma entidade específica, você poderá aplicar o mesmo padrão. Por exemplo, a URL a seguir se aplica à consulta Oportunidades Abertas em relação às oportunidades relacionadas a uma conta específica por meio da propriedade de navegação com valor de coleção opportunity_parent_account.

GET cc_WebAPI_ServiceURI/accounts(8f390c24-9c72-e511-80d4-00155d2a68d1)/opportunity_parent_account/?savedQuery=00000000-0000-0000-00aa-000010003001

Usar FetchXML personalizado

FetchXML é uma linguagem de consulta proprietária que fornece recursos para executar agregação. As consultas salvas e as consultas de usuário em savedquery EntityType e userquery EntityType respectivamente incluem uma propriedade fetchxml que define a consulta. Você pode usar o FetchXML diretamente com o IOrganizationService. O método RetrieveMultiple ou com o RetrieveMultipleRequest.Para obter mais informações:Criar consultas com FetchXML

Você pode passar o FetchXML codificado de URL como uma consulta ao conjunto de entidades correspondente à entidade raiz da consulta usando o parâmetro FetchXML para retornar os resultados da API Web. Por exemplo, você pode ter o seguinte FetchXML que contém a conta com a entidade.

<fetch mapping='logical'> 
   <entity name='account'>
      <attribute name='accountid'/> 
      <attribute name='name'/> 
</entity>
</fetch>

O valor codificado de URL desse FetchXML é mostrado aqui.

%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E

A maioria das linguagens de programação inclui uma função para codificação de URL de uma cadeia de caracteres. Por exemplo, no JavaScript você usa a função encodeURI. Você deve realizar a codificação de URL de qualquer solicitação que você enviar a qualquer serviço Web RESTful. Se você colar uma URL na barra de endereços do seu navegador, ele deverá realizar a codificação de URL do endereço automaticamente. O exemplo a seguir mostra uma solicitação GET usando o FetchXML mostrado anteriormente usando o caminho do conjunto de entidades para contas.

Solicitação

GET cc_WebAPI_ServiceURI/accounts?fetchXml=%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3C/entity%3E%3C/fetch%3E HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
  "@odata.context":"cc_WebAPI_ServiceURI/$metadata#accounts(accountid,name)","value":[
    {
      "@odata.etag":"W/\"506678\"","accountid":"89390c24-9c72-e511-80d4-00155d2a68d1","name":"Fourth Coffee (sample)"
    },{
      "@odata.etag":"W/\"502172\"","accountid":"8b390c24-9c72-e511-80d4-00155d2a68d1","name":"Litware, Inc. (sample)"
    },{
      "@odata.etag":"W/\"502174\"","accountid":"8d390c24-9c72-e511-80d4-00155d2a68d1","name":"Adventure Works (sample)"
    },{
      "@odata.etag":"W/\"506705\"","accountid":"8f390c24-9c72-e511-80d4-00155d2a68d1","name":"Fabrikam, Inc. (sample)"
    },{
      "@odata.etag":"W/\"506701\"","accountid":"91390c24-9c72-e511-80d4-00155d2a68d1","name":"Blue Yonder Airlines (sample)"
    },{
      "@odata.etag":"W/\"502180\"","accountid":"93390c24-9c72-e511-80d4-00155d2a68d1","name":"City Power & Light (sample)"
    },{
      "@odata.etag":"W/\"502182\"","accountid":"95390c24-9c72-e511-80d4-00155d2a68d1","name":"Contoso Pharmaceuticals (sample)"
    },{
      "@odata.etag":"W/\"506704\"","accountid":"97390c24-9c72-e511-80d4-00155d2a68d1","name":"Alpine Ski House (sample)"
    },{
      "@odata.etag":"W/\"502186\"","accountid":"99390c24-9c72-e511-80d4-00155d2a68d1","name":"A. Datum Corporation (sample)"
    },{
      "@odata.etag":"W/\"502188\"","accountid":"9b390c24-9c72-e511-80d4-00155d2a68d1","name":"Coho Winery (sample)"
    },{
      "@odata.etag":"W/\"504177\"","accountid":"0a3238d4-f973-e511-80d4-00155d2a68d1","name":"Litware, Inc."
    }
  ]
}

Observação

Resposta das consultas FetchXML que contêm entidades do link e seus atributos contêm caracteres especiais Unicode de modo que '.' torne-se '_x002e_' e '@' torne-se '_x0040_'.

Paginação com o FetchXML

Com o fetchXML, você pode aplicar paginação definindo os atributos page e count do elemento fetch. Por exemplo, para definir uma consulta para contas e limitar o número de entidades a dois e para retornar apenas a primeira página, execute o seguinte fetchXML:

<fetch mapping="logical" page="1" count="2">
 <entity name="account">
  <attribute name="accountid" />
  <attribute name="name" />
  <attribute name="industrycode" />
 <order attribute="name" />
 </entity>
</fetch>

Com uma solicitação que usa o fetchXML, você também pode solicitar um cookie de paginação e incluí-lo em sua consulta.Para obter mais informações:Grandes conjuntos de resultados em páginas com o FetchXML

Um cookie de paginação deve ser solicitado como uma anotação. Defina a preferência odata.include-annotations para usar (ou incluir) Microsoft.Dynamics.CRM.fetchxmlpagingcookie e uma propriedade @Microsoft.Dynamics.CRM.fetchxmlpagingcookie será retornada com o resultado.

Confira Também

Exemplo de dados de consulta de API da Web (C#)
Exemplo de dados de consulta da API Web (JavaScript do lado do cliente)
Executar operações usando A API
Compor solicitações de HTTP e lidar com erros
Consultar dados usando a API da Web
Criar uma entidade usando a API da Web
Recuperar uma entidade usando a API Web
Atualizar e excluir entidades que usam a API Web
Associar e desassociar entidades usando a API Web
Usar funções da API Web
Use ações API da Web
Executar operações em lote usando a API da WEB
Representar outro usuário usando API da Web
Executar operações condicionais usando A API

Microsoft Dynamics 365

Partilhar via

Recuperar e executar consultas predefinidas

Neste tópico

Consultas predefinidas

Aplicar uma consulta a qualquer coleção do tipo adequado

Usar FetchXML personalizado

Paginação com o FetchXML

Confira Também

Recursos adicionais