Consultar metadados usando a API da Web

Artigo
03/04/2017

Publicado: janeiro de 2017

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

Como Microsoft Dynamics 365 é um aplicativo orientado por metadados, os desenvolvedores podem precisar consultar os metadados do sistema em tempo de execução para adaptar a uma organização configurada. Esse recurso estará disponível por meio da API assim como o serviço da organização usando RetrieveMetadataChangesRequest e a classe do Microsoft.Xrm.Sdk.Metadata.Query namespace. Permite a API consultar metadados, mas não oferece a capacidade de tempo para detectar alterações nos metadados em determinado momento.

Neste tópico

Consultando o tipo de entidade de EntityMetadata

Use os tipos de enum nas operações $filter

Use os tipos de complexo nas operações $filter

Consultando atributos de EntityMetadata

Recuperar atributos

Consultando metadados de relacionamento

Consultando OptionSets global

Consultando o tipo de entidade de EntityMetadata

Você usará as mesma técnicas descritas em Consultar dados usando a API da Web quando consultar EntityMetadata, com poucas variações. Use o caminho de entidade EntityDefinitions para recuperar informações sobre o EntityMetadata EntityType. Entidades EntityMetadata contêm um monte de dados para que você deseje ser cuidadoso para apenas recuperar os dados que precisa. O exemplo a seguir mostra os dados devolvidos apenas para DisplayName, IsKnowledgeManagementEnabled, e propriedades EntitySetName de metadados para a entidade Account. O valor da propriedade MetadataId sempre é devolvido.

Solicitação

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=DisplayName,IsKnowledgeManagementEnabled,EntitySetName&$filter=SchemaName eq 'Account' 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#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 algumas propriedades do EntityMetadata com opções de consulta do sistema $select e pode usar $filter ou qualquer propriedades de uso primitivo ou valores de enumeração.

Não há limite no número de entidades de metadados que são retornados em uma consulta. Não há paginação. Todos os recursos serão retornados na primeira resposta.

Use os tipos de enum nas operações $filter

Quando você precisa filtrar as entidades de metadados com base no valor de uma propriedade que use a enumeração, você deve incluir a enumeração antes do namespace do valor da cadeia de caracteres. Os tipos do enum são usados como valores de propriedade de apenas entidades e tipos de metadados complexos. Por exemplo, se precisar filtrar as entidades baseadas na propriedade OwnershipType que usa o OwnershipTypes EnumType, você pode usar o $filter para devolver apenas aquelas entidades que são UserOwned.

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=OwnershipType eq Microsoft.Dynamics.CRM.OwnershipTypes'UserOwned'

Use os tipos de complexo nas operações $filter

Quando você precisa filtrar as entidades de metadados com base no valor de uma propriedade que use um tipo complexo, você deve incluir o caminho para o tipo primitivo subjacente. Os tipos complexos são usados como valores de propriedade de apenas entidades e metadados. Por exemplo, se precisar filtrar as entidades baseadas na propriedade CanCreateAttributes que usa o BooleanManagedProperty ComplexType, você pode usar o $filter para devolver apenas as entidades que têm um Value de true.

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=CanCreateAttributes/Value eq true

Este padrão funciona com BooleanManagedProperty ComplexType porque o valor primitivo a ser verificado tem um nível de profundidade. Entretanto, isso não funciona em propriedades de Label ComplexType.

Consultando atributos de EntityMetadata

Você pode ver atributos de entidade no contexto de uma entidade expandindo a propriedade de navegação da coleção principal Attributes, mas essa incluirá somente as propriedades comuns disponíveis no AttributeMetadata EntityType que todos os atributos compartilham. Por exemplo a consulta a seguir retornará o LogicalName da entidade e todos os Attributes expandidos que têm um valor AttributeType valor AttributeTypeCode EnumType de Picklist.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)?$select=LogicalName&$expand=Attributes($select=LogicalName;$filter=AttributeType eq Microsoft.Dynamics.CRM.AttributeTypeCode'Picklist')

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

Para recuperar as propriedades de um determinado tipo de atributo você deve converter a propriedade de navegação de da primeira coleção Attributes no tipo que você deseja. A consulta a seguir devolverá apenas os atributos PicklistAttributeMetadata e incluirá a LogicalName assim como expansão de OptionSet e das propriedades de navegação da primeira coleção GlobalOptionSet.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet,GlobalOptionSet

Observação

Apesar do fato que o OptionSet e propriedades de navegação de coleção principal GlobalOptionSet são definidas dentro do EnumAttributeMetadata EntityType você não pode converter os atributos para este tipo. Isso significa que se quiser a filtragem em outros tipos que também herdam essas propriedades (consulte Entity types that inherit from activitypointer), execute consultas separadas para a filtragem de cada tipo.

Outro exemplo deste é acessar a propriedade Precision disponível nos atributos MoneyAttributeMetadata EntityType e DecimalAttributeMetadata EntityType. Para acessar esta propriedade você deve converter um conjunto de atributos como MoneyAttributeMetadata ou DecimalAttributeMetadata. Um exemplo mostrando a conversão é mostrado aqui MoneyAttributeMetadata.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.MoneyAttributeMetadata?$select=LogicalName,Precision

Filtrar pelo nível necessário

A propriedade AttributeMetadata EntityTypeRequiredLevel usa uma propriedade especial AttributeRequiredLevelManagedProperty ComplexType onde a propriedade Value é um AttributeRequiredLevel EnumType. Nesse caso você deve combinar os padrões localizados em Use os tipos de complexo nas operações $filter e Use os tipos de enum nas operações $filterpara filtrar para essa propriedade exclusiva. A consulta a seguir filtrará os atributos da entidade de conta que são ApplicationRequired.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'

Recuperar atributos

Quando você souber o MetadataId para EntityMetadata e o AttributeMetadata, você pode recuperar um atributo individual e acessar os valores de propriedade usando uma consulta do procedimento. Essa consulta recupera LogicalName a propriedade de atributo bem como expandindo a propriedade de navegação de coleção principal OptionSet. Observe que você deve converter o atributo como Microsoft.Dynamics.CRM.PicklistAttributeMetadata para acessar a propriedade de navegação de coleção principal OptionSet.

Solicitação

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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": "cc_WebAPI_ServiceURI/$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": "cc_WebAPI_ServiceURI/$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 de atributos e não desejar apenas os valores de uma propriedade de navegação de coleção principal como OptionsSet, você pode incluir aquele no URL e limitar as propriedades com uma opção de consulta do sistema $select de uma forma de consulta mais eficiente. No exemplo a seguir somente a propriedade Options de OptionSet está incluída.

Solicitação

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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": "cc_WebAPI_ServiceURI/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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"
}

Consultando metadados de relacionamento

Você pode recuperar metadados de relacionamento no contexto de uma determinada entidade da mesma forma que você pode ver os atributos. As propriedade de navegação de coleção principal ManyToManyRelationships, ManyToOneRelationships e OneToManyRelationships pode ser consultada como a propriedade de navegação de coleção principal Attributes.Para obter mais informações:Consultando atributos de EntityMetadata

Entretanto, os relacionamentos de entidade também podem ser consultados usando o conjunto de entidades RelationshipDefinitions. Você pode usar uma consulta como a seguir da propriedade SchemaName para cada relação.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions?$select=SchemaName

Consulte propriedades disponíveis para o conjunto de entidades são limitadas para RelationshipMetadataBase EntityType. Para acessar propriedades dos tipos de entidade herdam RelationshipMetadataBase de que você precisa incluir a uma consulta da conversão para retornar somente OneToManyRelationshipMetadata EntityType.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName

Como as entidades retornadas são digitadas por OneToManyRelationshipMetadata, você pode filtrar as propriedades como ReferencedEntity para criar uma consulta para devolver as relações de entidade uma a uma de uma entidade específica, como a entidade de conta exibida na consulta a seguir:

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName&$filter=ReferencedEntity eq 'account'

Aquela consulta devolverá essencialmente os mesmos resultados que a consulta a seguir, que é filtrada porque está incluída na propriedade de navegação de coleção principal EntityMetadataOneToManyRelationships da entidade da conta. Essa é a diferença para a consulta que anterior não precisa conhecer MetadataId da entidade conta.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/OneToManyRelationships?$select=SchemaName

Consultando OptionSets global

Você pode usar o caminho da entidade GlobalOptionSetDefinitions para recuperar informações sobre conjuntos de opções globais, porém o caminho não oferece suporte ao uso de consulta padrão do sistema $filter. Assim, se você conhecer um MetadataId para um conjunto de opções globais específico, só é possível recuperar todos. Você também pode acessar a definição de um conjunto de opções globais na propriedade única avaliada de navegação GlobalOptionSet para qualquer atributo que ele usa. Está disponível para todos Entity types that inherit from activitypointer.Para obter mais informações:Recuperar atributos

Confira Também

Use o API da Web com metadados do Dynamics 365
Recuperar metadados por nome ou por MetadataId
Criar e atualizar definições de entidade usando API da Web
Criar e atualizar relacionamentos de entidade usando API da Web

Microsoft Dynamics 365

Compartilhar via

Consultar metadados usando a API da Web

Neste tópico

Consultando o tipo de entidade de EntityMetadata

Use os tipos de enum nas operações $filter

Use os tipos de complexo nas operações $filter

Consultando atributos de EntityMetadata

Filtrar pelo nível necessário

Recuperar atributos

Consultando metadados de relacionamento

Consultando OptionSets global

Confira Também

Recursos adicionais