Consultar definiciones de tabla con la API web

Artículo
03/15/2023

Dado que Microsoft Dataverse es una aplicación basada en metadatos, los desarrolladores pueden necesitar consultar las definiciones del sistema en tiempo de ejecución para adaptarse a cómo se ha configurado una organización. Esta funcionalidad usa un estilo de RESTful de la consulta.

Nota

También puede generar una consulta con un estilo basado en objetos usando EntityQueryExpression ComplexType con RetrieveMetadataChanges Function. Esta función permite capturar cambios en las definiciones de la tabla entre dos períodos de tiempo, así como devolver un conjunto limitado de definiciones descritas por una consulta que especifique. Más información: Definiciones de esquema de consulta

Consultar el tipo de entidad EntityMetadata

Utilizará las mismas técnicas descritas en Consultar datos mediante 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 la definición para la entidad Account. El valor de la propiedad MetadataId siempre se devuelve.

Solicitud:

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

Respuesta:

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

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.

Límite de idiomas devueltos

Cuando un entorno tiene muchos idiomas aprovisionados, la cantidad de datos devueltos puede crecer mucho. Para obtener el mejor rendimiento, limite las etiquetas de idioma devueltas mediante el parámetro LabelLanguages con el valor LCID del idioma que desea devolver.

Los códigos de idioma son identificadores de configuración regional de cuatro o cinco dígitos. Los valores de identificadores de configuración regional válidos pueden encontrarse en el gráfico de identificadores de configuración regional (LCID).

Por ejemplo, agregar lo siguiente limitará las etiquetas de idioma localizadas al inglés: &LabelLanguages=1033.

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 OwnershipTypes Enumtype, puede usar el siguiente $filter para devolver únicamente las entidades que son UserOwned.

GET [Organization URI]/api/data/v9.2/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 tengan un Value de true.

GET [Organization URI]/api/data/v9.2/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. Sin embargo, esto no funciona en las 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 atributos expandidos que tengan un valor de AttributeType igual al valor de AttributeTypeCode EnumType 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')

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á solo los atributos PicklistAttributeMetadata EntityType e incluirá además los LogicalName y también expandirá las propiedades de navegación valoradas como colección de OptionSet y GlobalOptionSet.

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/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 (consulte Tipos de entidades que heredan de EnumAttributeMetadata ), debe realizar consultas aparte 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 EntityType o DecimalAttributeMetadata EntityType. Un ejemplo que muestra la conversión a MoneyAttributeMetadata se muestra a continuación.

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

Filtrar por nivel requerido

La propiedad RequiredLevel de AttributeMetadata EntityType utiliza un AttributeRequiredLevelManagedProperty ComplexType donde la propiedad Value es un AttributeRequiredLevel EnumType. En este caso, debe combinar patrones de Utilizar tipos complejos en operaciones $filter y Utilizar 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 sean ApplicationRequired.

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

Recuperar atributos

Si conoce el MetadataId para EntityMetadata y AttributeMetadata, o el valor LogicalName de cualquiera de ellos, puede recuperar un atributo individual y acceder a los valores de las propiedades 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. Debe convertir el atributo como Microsoft.Dynamics.CRM.PicklistAttributeMetadata para acceder a la propiedad de navegación valorada como colección OptionSet.

Solicitud:

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

Respuesta:

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

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 más eficaz. En el siguiente ejemplo solo la propiedad Options del OptionSet está incluida.

Solicitud:

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

Respuesta:

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

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 [Organization URI]/api/data/v9.2/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 [Organization URI]/api/data/v9.2/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 [Organization URI]/api/data/v9.2/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 de 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 [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/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, solo puede recuperar un solo conjunto de opciones global mediante el MetadataId o el nombre único.

Ejemplo: por MetadataId

El siguiente ejemplo muestra cómo recuperar un conjunto de opciones global usando el MetadataId.

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

Ejemplo por nombre

El siguiente ejemplo muestra cómo recuperar un conjunto de opciones global por nombre:

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

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 atributo que la utilice. Esto está disponible para todos los tipos derivados EnumAttributeMetadata EntityType. Más información: Recuperar atributos

Consultar también

Usar la API web con metadatos de Dataverse
Recuperar metadatos por nombre o identificador de metadatos
Entidades de metadatos y atributos con la API web
Relaciones de entidades de metadatos con la API web
Ejemplo de operaciones de esquema de tabla de API web
Ejemplo de operaciones de esquema de tabla de API web (C#)

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).

Compartir a través de

Consultar definiciones de tabla con la API web

Consultar el tipo de entidad EntityMetadata

Límite de idiomas devueltos

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

Ejemplo: por MetadataId

Ejemplo por nombre

Consultar también

Recursos adicionales