Consulta de metadatos utilizando la API web

Artículo
03/04/2017

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Puesto que Microsoft Dynamics 365 es una aplicación basada en metadatos, los desarrolladores pueden necesitar consultar los metadatos del sistema en tiempo de ejecución para adaptarse a la forma en que se ha configurado una organización. Esta característica está disponible mediante la API web así como usando el servicio de la organización mediante la RetrieveMetadataChangesRequest y las clases del espacio de nombres Microsoft.Xrm.Sdk.Metadata.Query. La API web permite consultar metadatos pero no ofrece la posibilidad de detectar cambios en los metadatos en un momento en el tiempo.

En este tema

Consultar el tipo de entidad EntityMetadata

Use tipos de enumeración en operaciones $filter

Use tipos complejos en operaciones $filter

Consultar atributos EntityMetadata

Recuperar atributos

Consultar metadatos de relaciones

Consultar conjuntos de opciones globales

Consultar el tipo de entidad EntityMetadata

Usará las mismas técnicas descritas en Consultar datos utilizando la API web cuando consulte EntityMetadata, con algunas variaciones. Use la ruta del conjunto de entidades EntityDefinitions para recuperar información acerca del EntityMetadata EntityType. Las entidades de EntityMetadata contienen muchos datos por lo que deberá tener cuidado de recuperar solo los datos necesarios. El siguiente ejemplo muestra los datos devueltos solo para las propiedades DisplayName, IsKnowledgeManagementEnabled y EntitySetName de los metadatos de la entidad Account. El valor de la propiedad MetadataId siempre se devuelve.

Solicitud

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

Respuesta

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"
  }
 ]
}

Puede usar cualquiera de las propiedades EntityMetadata con opciones de consulta del sistema $select y puede usar $filter en cualquier propiedad que use valores primitivos o de enumeración.

No tiene hay límites en el número al número de entidades de metadatos que serán devueltas en una consulta. No hay paginación. Se devolverán todos los recursos que coincidan en la primera respuesta.

Use tipos de enumeración en operaciones $filter

Cuando necesite filtrar entidades de metadatos basadas en el valor de una propiedad que use una enumeración, debe incluir el espacio de nombres de la enumeración delante del valor de cadena. Los tipos de enumeración se utilizan como valores de propiedad solo en entidades de metadatos y tipos complejos. Por ejemplo, si necesita filtrar entidades en función de la propiedad OwnershipType, que usa el OwnershipTypes EnumType, puede usar el siguiente $filter para devolver únicamente las entidades que son UserOwned.

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

Use tipos complejos en operaciones $filter

Cuando necesite filtrar entidades de metadatos basadas en el valor de una propiedad que use un tipo complejo, debe incluir la ruta al tipo primitivo subyacente. Los tipos complejos se utilizan como valores de propiedad solo en entidades de metadatos. Por ejemplo, si necesita filtrar entidades en función de la propiedad CanCreateAttributes, que usa el BooleanManagedProperty ComplexType, puede usar el siguiente $filter para devolver únicamente las entidades que tienen un Value de true.

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

Este modelo funciona con BooleanManagedProperty ComplexType porque el valor primitivo a comprobar tiene un nivel de profundidad. No obstante, esto no funciona en propiedades de Label ComplexType.

Consultar atributos EntityMetadata

Puede ver atributos de entidad en el contexto de una entidad expandiendo la propiedad de navegación valorada como colección Attributes, pero esto solo incluirá las propiedades comunes disponibles en el AttributeMetadata EntityType que todos los atributos comparten. Por ejemplo, la siguiente consulta devolverá el LogicalName de la entidad y todos los Attributes expandidos que tengan un valor de AttributeType igual al valor de 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')

Pero no puede incluir las propiedades navegación valoradas como colección OptionSet o GlobalOptionSet que los atributos PicklistAttributeMetadata EntityType tienen en el filtro $select de esta consulta.

Para recuperar las propiedades de un tipo específico de atributo debe convertir la propiedad de navegación valorada como colección Attributes al tipo que desee. La siguiente consulta devolverá sólo los atributos PicklistAttributeMetadata e incluirá el LogicalName además de expandir las propiedades de navegación valoradas como colección OptionSet o GlobalOptionSet.

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

Nota

A pesar de que las propiedades de navegación valoradas como colección OptionSet y GlobalOptionSet se definen en EnumAttributeMetadata EntityType, no puede convertir los atributos a este tipo. Esto significa que si desea filtrar por otros tipos que también hereden estas propiedades ( Entity types that inherit from activitypointer), debe realizar consultas separadas para filtrar por cada tipo.

Otro ejemplo de esto es acceder a la propiedad Precision disponible en los atributos MoneyAttributeMetadata EntityType y DecimalAttributeMetadata EntityType. Para acceder a esta propiedad debe convertir la colección de atributos como MoneyAttributeMetadata o DecimalAttributeMetadata. Un ejemplo que muestra la conversión a MoneyAttributeMetadata se muestra a continuación.

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

Filtrar por nivel requerido

La propiedad AttributeMetadata EntityTypeRequiredLevel usa un AttributeRequiredLevelManagedProperty ComplexType especial donde la propiedad Value es un AttributeRequiredLevel EnumType. En este caso debe combinar los patrones que se encuentran en Use tipos complejos en operaciones $filter y Use tipos de enumeración en operaciones $filter para filtrar por esta propiedad única. La siguiente consulta filtrará esos atributos en la entidad de cuenta que son 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

Cuando conoce el MetadataId para los EntityMetadata y AttributeMetadata, puede recuperar un atributo individual y tener acceder a los valores de propiedad mediante una consulta como la siguiente. Esta consulta recupera la propiedad LogicalName del atributo además de expandir la propiedad de navegación valorada como colección OptionSet. Tenga en cuenta que debe convertir el atributo como Microsoft.Dynamics.CRM.PicklistAttributeMetadata para obtener acceso a la propiedad de navegación valorada como colección OptionSet.

Solicitud

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

Respuesta

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
 }
}

Si no requiere ninguna propiedad del atributo y solo desea los valores de una propiedad de navegación valorada como colección como OptionsSet, puede incluir esto en la URL y limitar las propiedades con una opción de consulta del sistema $select para una consulta algo más eficaz. En el siguiente ejemplo solo la propiedad Options del OptionSet está incluida.

Solicitud

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

Respuesta

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"
}

Consultar metadatos de relaciones

Puede recuperar metadatos de relaciones en el contexto de una entidad determinada en gran parte de la misma forma que pueda consultar atributos. Las propiedades de navegación valorada como colección ManyToManyRelationships, ManyToOneRelationships y OneToManyRelationships se pueden consultar como la propiedad de navegación valorada como colección Attributes.Más información:Consultar atributos EntityMetadata

Sin embargo, las relaciones entre entidades también se pueden consultar con el conjunto de entidades RelationshipDefinitions. Puede usar una consulta como la siguiente para obtener la propiedad SchemaName para cada relación.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions?$select=SchemaName

Las propiedades disponibles al consultar este conjunto de entidades se limitan a las que están en RelationshipMetadataBase EntityType. Para tener acceso a propiedades de los tipos de entidad que se heredan de RelationshipMetadataBase es necesario incluir una conversión en la consulta como la siguiente para devolver solo OneToManyRelationshipMetadata EntityType.

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

Puesto que las entidades devueltas tienen el tipo OneToManyRelationshipMetadata, puede filtrar por propiedades como ReferencedEntity para crear una consulta para devolver solo las relaciones entre entidades de una a varias para una entidad específica, como la entidad de cuenta como se muestra en la siguiente consulta:

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

Esa consulta esencialmente devolverá los mismos resultados que la siguiente consulta, que se filtra porque está incluida en propiedad de navegación valorada como colección EntityMetadataOneToManyRelationships de la entidad de cuenta. La diferencia es que para la consulta anterior no necesita saber el MetadataId para la entidad de cuenta.

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

Consultar conjuntos de opciones globales

Puede usar la ruta de conjuntos de entidades GlobalOptionSetDefinitions para recuperar información sobre conjuntos de opciones globales, pero esta ruta de acceso no admite el uso de la opción de consulta del sistema $filter. Por lo tanto, a menos que conozca el MetadataId para un conjunto de opciones globales específico, solo puede recuperarlas todas. También puede obtener acceso a la definición de un conjunto de opciones globales dentro de la propiedad de navegación valorada como colección GlobalOptionSet para cualquier atributos que la utilice. Esto está disponible para todos los Entity types that inherit from activitypointer.Más información:Recuperar atributos

Ver también

Usar la API web con metadatos de Dynamics 365
Recuperar metadatos por nombre o identificador de metadatos
Crear y actualizar definiciones de entidad mediante la API web
Crear y actualizar relaciones de entidad mediante la API web

Microsoft Dynamics 365

Consulta de metadatos utilizando la API web

En este tema

Consultar el tipo de entidad EntityMetadata

Use tipos de enumeración en operaciones $filter

Use tipos complejos en operaciones $filter

Consultar atributos EntityMetadata

Filtrar por nivel requerido

Recuperar atributos

Consultar metadatos de relaciones

Consultar conjuntos de opciones globales

Ver también

Recursos adicionales