Definições de tabela de consulta usando a API Web

Como o Microsoft Dataverse é um aplicativo controlado por metadados, talvez os desenvolvedores precisem consultar as definições do sistema em tempo de execução para se adaptarem à forma como uma organização é configurada. Essa funcionalidade usa um estilo de consulta RESTful.

Consultar o tipo de entidade EntityMetadata

Use as mesmas técnicas descritas em dados de consulta usando a API Web ao consultar EntityMetadata, com algumas variações. Use o caminho do conjunto de entidades EntityDefinitions para recuperar informações sobre o EntityMetadata EntityType. As entidades EntityMetadata contêm muitos dados, portanto, recuperam apenas os dados necessários. O exemplo a seguir mostra os dados retornados apenas para as propriedades DisplayName, IsKnowledgeManagementEnabled, e EntitySetName da definição para a entidade Account. O valor da MetadataId propriedade sempre é retornado.

Solicitação:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=DisplayName,IsKnowledgeManagementEnabled,EntitySetName 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": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(DisplayName,IsKnowledgeManagementEnabled,EntitySetName)",  
 "value": [  
  {  
   "DisplayName": {  
    "LocalizedLabels": [  
     {  
      "Label": "Account",  
      "LanguageCode": 1033,  
      "IsManaged": true,  
      "MetadataId": "2a4901bf-2241-db11-898a-0007e9e17ebd",  
      "HasChanged": null  
     }  
    ],  
    "UserLocalizedLabel": {  
     "Label": "Account",  
     "LanguageCode": 1033,  
     "IsManaged": true,  
     "MetadataId": "2a4901bf-2241-db11-898a-0007e9e17ebd",  
     "HasChanged": null  
    }  
   },  
   "IsKnowledgeManagementEnabled": false,  
   "EntitySetName": "accounts",  
   "MetadataId": "70816501-edb9-4740-a16c-6a5efbc05d84"  
  }  
 ]  
}  
  

Você pode usar qualquer uma das propriedades com EntityMetadata opções $select de consulta do sistema. Você pode usar $filter em qualquer propriedade que use valores primitivos ou de enumeração.

Não há limites para o número de entidades de metadados retornadas por uma consulta. Não há paginação. A primeira resposta retorna todos os recursos correspondentes.

Limitar idiomas retornados

Quando um ambiente tem muitos idiomas provisionados, a quantidade de dados retornados pode aumentar. Para obter melhor desempenho, limite os rótulos de idioma retornados usando o LabelLanguages parâmetro com o valor LCID do idioma que você deseja retornar.

Os códigos de idioma são IDs de localidade de quatro ou cinco dígitos. Os valores de ID de localidade válidos podem ser encontrados em Gráfico de LCID (ID de localidade).

Por exemplo, acrescentar o seguinte valor limita os rótulos de idioma localizados ao inglês: &LabelLanguages=1033.

Usar tipos de enumeração em operações com $filter

Quando você precisar filtrar entidades de metadados com base no valor de uma propriedade que usa uma enumeração, inclua o namespace da enumeração antes do valor da cadeia de caracteres. Os tipos de enumeração são usados como valores de propriedade somente em entidades de metadados e tipos complexos. Por exemplo, se você precisar filtrar entidades com base na propriedade OwnershipType que usa o Enumtype OwnershipTypes, use o seguinte $filter para retornar apenas as entidades que são UserOwned.

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=LogicalName&$filter=OwnershipType eq Microsoft.Dynamics.CRM.OwnershipTypes'UserOwned'  

Usar tipos complexos em operações de $filter

Quando você precisar filtrar entidades de metadados com base no valor de uma propriedade que usa um tipo complexo, inclua o caminho para o tipo primitivo subjacente. Tipos complexos são usados como valores de propriedade apenas em entidades de metadados. Por exemplo, se você precisar filtrar entidades com base na CanCreateAttributes propriedade, que usa o BooleanManagedProperty ComplexType, use o seguinte $filter para retornar apenas as entidades que têm um Value de true.

GET [Organization URI]/api/data/v9.2/EntityDefinitions?$select=LogicalName&$filter=CanCreateAttributes/Value eq true  

Esse padrão funciona com BooleanManagedProperty ComplexType porque o valor primitivo a ser verificado é de um nível profundo. No entanto, esse padrão não funciona em propriedades de Label ComplexType.

Consultar atributos de EntityMetadata

Você pode consultar atributos de entidade no contexto de uma entidade expandindo a Attributes propriedade de navegação com valor de coleção. Essa abordagem inclui apenas as propriedades comuns disponíveis no AttributeMetadata EntityType que todos os atributos compartilham. Por exemplo, a consulta a seguir retorna o LogicalName da entidade e todos os Atributos expandidos que têm um AttributeType valor igual ao valor do EnumType AttributeTypeCode de Picklist.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=LogicalName&$expand=Attributes($select=LogicalName;$filter=AttributeType eq Microsoft.Dynamics.CRM.AttributeTypeCode'Picklist')  

Mas você não pode incluir as propriedades de navegação com valor de coleção OptionSet ou GlobalOptionSet que os atributos PicklistAttributeMetadata EntityType possuem dentro do $select filtro dessa consulta.

Para recuperar as propriedades de um tipo específico de atributo, converta a Attributes propriedade de navegação com valor de coleção para o tipo desejado. A consulta a seguir retorna apenas os atributos PicklistAttributeMetadata EntityType . Inclui o LogicalName e expande as propriedades de navegação de valor de coleção OptionSet e GlobalOptionSet.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet,GlobalOptionSet  

Outro exemplo dessa limitação é acessar a Precision propriedade disponível nos atributos MoneyAttributeMetadata EntityType e DecimalAttributeMetadata EntityType . Para acessar essa propriedade, você deve converter a coleção de atributos como MoneyAttributeMetadata EntityType ou DecimalAttributeMetadata EntityType. Um exemplo mostrando o casting para MoneyAttributeMetadata é apresentado aqui.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes/Microsoft.Dynamics.CRM.MoneyAttributeMetadata?$select=LogicalName,Precision

Filtrar por nível necessário

A propriedade AttributeMetadata EntityTypeRequiredLevel usa um AttributeRequiredLevelManagedProperty ComplexType especial em que a Value propriedade é um AttributeRequiredLevel EnumType. Para filtrar por essa propriedade exclusiva, combine padrões encontrados em Usar tipos complexos em operações de $filter e use tipos de enumeração em operações de $filter. A consulta seguinte filtra os atributos na entidade de conta que são obrigatórios para a aplicação.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'  

Recuperar atributos

Quando você souber o MetadataId para ambos os EntityMetadata e AttributeMetadata, ou o valor de LogicalName para qualquer um deles, você pode obter um atributo específico e acessar os valores das propriedades usando uma consulta como no exemplo a seguir. Essa consulta recupera a LogicalName propriedade do atributo e expande a OptionSet propriedade de navegação com valor de coleção. Você deve converter o atributo como um Microsoft.Dynamics.CRM.PicklistAttributeMetadata para acessar a OptionSet propriedade de navegação com valor de coleção.

Solicitação:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet HTTP/1.1  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
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": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet)/$entity",  
"LogicalName": "preferredappointmentdaycode",  
"MetadataId": "5967e7cc-afbb-4c10-bf7e-e7ef430c52be",  
"OptionSet@odata.context": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet/$entity",  
"OptionSet": {  
 "Options": [  
  {  
   "Value": 0,  
   "Label": {  
    "LocalizedLabels": [  
     {  
      "Label": "Sunday",  
      "LanguageCode": 1033,  
      "IsManaged": true,  
      "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
      "HasChanged": null  
     }  
    ],  
    "UserLocalizedLabel": {  
     "Label": "Sunday",  
     "LanguageCode": 1033,  
     "IsManaged": true,  
     "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
     "HasChanged": null  
    }  
   },  
   "Description": {  
    "LocalizedLabels": [],  
    "UserLocalizedLabel": null  
   },  
   "Color": null,  
   "IsManaged": true,  
   "MetadataId": null,  
   "HasChanged": null  
  }  
Additional options removed for brevity  
 ],  
 "Description": {  
  "LocalizedLabels": [  
   {  
    "Label": "Day of the week that the account prefers for scheduling service activities.",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "1b67144d-ece0-4e83-a38b-b4d48e3f35d5",  
    "HasChanged": null  
   }  
  ],  
  "UserLocalizedLabel": {  
   "Label": "Day of the week that the account prefers for scheduling service activities.",  
   "LanguageCode": 1033,  
   "IsManaged": true,  
   "MetadataId": "1b67144d-ece0-4e83-a38b-b4d48e3f35d5",  
   "HasChanged": null  
  }  
 },  
 "DisplayName": {  
  "LocalizedLabels": [  
   {  
    "Label": "Preferred Day",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "ebb7e979-f9e3-40cd-a86d-50b479b1c5a4",  
    "HasChanged": null  
   }  
  ],  
  "UserLocalizedLabel": {  
   "Label": "Preferred Day",  
   "LanguageCode": 1033,  
   "IsManaged": true,  
   "MetadataId": "ebb7e979-f9e3-40cd-a86d-50b479b1c5a4",  
   "HasChanged": null  
  }  
 },  
 "IsCustomOptionSet": false,  
 "IsGlobal": false,  
 "IsManaged": true,  
 "IsCustomizable": {  
  "Value": true,  
  "CanBeChanged": false,  
  "ManagedPropertyLogicalName": "iscustomizable"  
 },  
 "Name": "account_preferredappointmentdaycode",  
 "OptionSetType": "Picklist",  
 "IntroducedVersion": null,  
 "MetadataId": "53f9933c-18a0-40a6-b4a5-b9610a101735",  
 "HasChanged": null  
}  
}  

Se você não precisar de nenhuma propriedade do atributo e quiser apenas os valores de uma propriedade de navegação com valor de coleção, como OptionSet, inclua essa propriedade na URL e limite as propriedades usando uma $select opção de consulta do sistema para uma consulta mais eficiente. No exemplo a seguir, somente a Options propriedade do OptionSet é incluída.

Solicitação:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet?$select=Options HTTP/1.1  
Accept: application/json  
Content-Type: application/json; charset=utf-8  
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": "[Organization URI]/api/data/v9.2/$metadata#EntityDefinitions('account')/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet(Options)/$entity",  
"Options": [{  
  "Value": 0,  
  "Label": {  
   "LocalizedLabels": [{  
    "Label": "Sunday",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
    "HasChanged": null  
   }],  
   "UserLocalizedLabel": {  
    "Label": "Sunday",  
    "LanguageCode": 1033,  
    "IsManaged": true,  
    "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",  
    "HasChanged": null  
   }  
  },  
  "Description": {  
   "LocalizedLabels": [],  
   "UserLocalizedLabel": null  
  },  
  "Color": null,  
  "IsManaged": true,  
  "MetadataId": null,  
  "HasChanged": null  
 }  
Additional options removed for brevity  
],  
"MetadataId": "53f9933c-18a0-40a6-b4a5-b9610a101735"  
}  

Metadados de relação de consulta

Você pode recuperar metadados de relação no contexto de uma determinada entidade, semelhante à forma como consulta atributos. Você pode consultar as propriedades de navegação com valor de coleção ManyToManyRelationships, ManyToOneRelationships e OneToManyRelationships da mesma forma que a propriedade de navegação com valor de coleção Attributes. Para obter mais informações, consulte Atributos QueryEntityMetadata.

No entanto, você também pode consultar relações de entidade usando o RelationshipDefinitions conjunto de entidades. Para obter a SchemaName propriedade de cada relação, use uma consulta como o exemplo a seguir.

GET [Organization URI]/api/data/v9.2/RelationshipDefinitions?$select=SchemaName  

As propriedades disponíveis ao consultar esse conjunto de entidades são limitadas às do EntityType RelationshipMetadataBase. Para acessar propriedades dos tipos de entidade que herdam de RelationshipMetadataBase, inclua uma conversão na consulta como no exemplo a seguir para retornar apenas OneToManyRelationshipMetadata EntityType.

GET [Organization URI]/api/data/v9.2/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName  

Como as entidades retornadas são tipadas como OneToManyRelationshipMetadata, você pode filtrar em propriedades, como ReferencedEntity, para construir uma consulta que retorna apenas as relações de entidade de um para muitos para uma entidade específica, como a entidade conta mostrada na seguinte consulta:

GET [Organization URI]/api/data/v9.2/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName&$filter=ReferencedEntity eq 'account' 

Essa consulta retorna essencialmente os mesmos resultados da consulta a seguir, que é filtrada porque está incluída na EntityMetadataOneToManyRelationships propriedade de navegação com valor de coleção da entidade da conta. A diferença é que, para a consulta anterior, você não precisa saber o MetadataId da entidade da conta.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/OneToManyRelationships?$select=SchemaName  

Consultar conjuntos de opções globais

Você pode usar o GlobalOptionSetDefinitions caminho de conjunto de entidades para recuperar informações sobre conjuntos de opções globais, mas esse caminho não dá suporte ao uso da opção de consulta do $filter sistema. Portanto, você só pode recuperar um único conjunto de opções globais usando o MetadataId ou o nome exclusivo.

Exemplo: Por MetadataId

O exemplo a seguir mostra como recuperar um conjunto de opções global usando o MetadataId.

GET [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions(08fa2cb2-e3fe-497a-9b5d-ee887f5cc3cd)

Exemplo por nome

O exemplo a seguir mostra como recuperar uma opção global definida pelo nome:

GET [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions(Name='incident_caseorigincode')

Você também pode acessar a definição de um conjunto de opções global de dentro da GlobalOptionSet propriedade de navegação com valor único para qualquer atributo que a use. Essa propriedade está disponível para todos os tipos derivados de EnumAttributeMetadata EntityType. Para obter mais informações, consulte Recuperar atributos.

Consulte também

Usar a API Web com metadados do Dataverse
Recuperar metadados por nome ou MetadadosId
Entidades e atributos de metadados usando a API Web
Relações de entidade de metadados usando a API Web
Exemplo de operações de esquema de tabela da API Web
Exemplo de operações de esquema de tabela de API Web (C#)