Compartir a través de

Consulta de definiciones de tabla mediante la API web

Dado que Microsoft Dataverse es una aplicación controlada por metadatos, es posible que los desarrolladores necesiten consultar las definiciones del sistema en tiempo de ejecución para adaptarse a cómo se configura una organización. Esta funcionalidad usa un estilo de consulta RESTful.

Nota

También puede construir una consulta mediante un estilo basado en objetos mediante EntityQueryExpression ComplexType con la función RetrieveMetadataChanges. Esta función captura los cambios en las definiciones de tabla entre dos períodos de tiempo y devuelve un conjunto limitado de definiciones descritas por una consulta que especifique. Para obtener más información, consulte Definiciones de esquema de consulta.

Consulta la entidad de tipo EntityMetadata

Use las mismas técnicas descritas en Consulta de datos mediante la API web al consultar EntityMetadata, con algunas variaciones. Use la ruta del conjunto de entidades EntityDefinitions para recuperar información acerca del EntityMetadata EntityType. Las entidades EntityMetadata contienen una gran cantidad de datos, por lo que solo se recuperan los datos que necesita. 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 EntityMetadata propiedades con $select opciones de consulta del sistema. Puede usar $filter en cualquier propiedad que use valores primitivos o de enumeración.

No hay límites en el número de entidades de metadatos que devuelve una consulta. No hay paginación. La primera respuesta devuelve todos los recursos coincidentes.

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 con el LabelLanguages 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 válidos de ID de configuración regional pueden encontrarse en el gráfico de identificadores de configuración regional (LCID).

Por ejemplo, al anexar el siguiente valor se limitan las etiquetas de idioma localizadas al inglés: &LabelLanguages=1033.

Utilice tipos de enumeración en operaciones $filter

Cuando necesite filtrar entidades de metadatos en función del valor de una propiedad que use una enumeración, incluya el espacio de nombres de la enumeración antes 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 las entidades en función de la propiedad OwnershipType, que usa el tipo de enumeración OwnershipTypes Enumtype, use lo siguiente $filter para devolver solo 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 las entidades de metadatos en función del valor de una propiedad que usa un tipo complejo, incluya la ruta de acceso 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 CanCreateAttributes propiedad, que usa el ComplexType BooleanManagedProperty, utilice lo siguiente $filter para devolver solo aquellas entidades que tienen 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, este patrón no funciona en las propiedades de Label ComplexType.

Consulta de atributos EntityMetadata

Puede consultar atributos de entidad en el contexto de una entidad expandiendo la Attributes propiedad de navegación con valores de colección. Este enfoque solo incluye las propiedades comunes disponibles en AttributeMetadata EntityType que comparten todos los atributos. Por ejemplo, la consulta siguiente devuelve el LogicalName de la entidad y todos los atributos expandidos que tienen un AttributeType valor igual al valor 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 de navegación valoradas como colecciones, OptionSet o GlobalOptionSet que tienen los atributos PicklistAttributeMetadata EntityType en el filtro $select de esta consulta.

Para recuperar las propiedades de un tipo específico de atributo, convierta la Attributes propiedad de navegación con valores de colección al tipo que desee. La consulta siguiente devuelve solo los atributos PicklistAttributeMetadata EntityType . Incluye el LogicalName y expande las propiedades de navegación con valor de colección OptionSet y GlobalOptionSet.

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

Nota

Aunque las propiedades de navegación con valor de colección OptionSet y GlobalOptionSet se definen en EnumAttributeMetadata EntityType, no se pueden transformar los atributos a este tipo. Esta limitación significa que debe realizar consultas independientes para filtrar por otros tipos que heredan estas propiedades. Para obtener más información, consulte Tipos de entidad que heredan de EnumAttributeMetadata.

Otro ejemplo de esta limitación es acceder a la propiedad disponible en los Precision 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 necesario

La propiedad AttributeMetadata EntityTypeRequiredLevel utiliza un AttributeRequiredLevelManagedProperty ComplexType especial donde la propiedad Value es un AttributeRequiredLevel EnumType. Para filtrar por esta propiedad única, combine patrones que se encuentran en Uso de tipos complejos en operaciones de $filter y Uso de tipos de enumeración en operaciones de $filter. La consulta siguiente filtra esos atributos en la entidad de cuenta que tienen el atributo ApplicationRequired.

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

Recuperación de atributos

Cuando conoces el MetadataId tanto para el EntityMetadata como para el AttributeMetadata, o el valor del LogicalName para cualquiera de ellos, puedes recuperar un atributo individual y acceder a los valores de propiedad mediante una consulta como en el siguiente ejemplo. Esta consulta recupera la LogicalName propiedad del atributo y expande la OptionSet propiedad de navegación con valores de colección. Debe convertir el atributo en Microsoft.Dynamics.CRM.PicklistAttributeMetadata para acceder a la propiedad de navegación de 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 necesita ninguna propiedad del atributo y solo quiere los valores de una propiedad de navegación con valores de colección, como OptionSet, incluya esa propiedad en la dirección URL y limite las propiedades mediante una $select opción de consulta del sistema para una consulta más eficaz. En el ejemplo siguiente, solo se incluye la propiedad Options de la OptionSet.

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

Metadatos de la relación de consulta

Puede recuperar metadatos de relación en el contexto de una entidad determinada, de forma similar a la forma de consultar atributos. Puede consultar las propiedades de navegación con valores de colección ManyToManyRelationships, ManyToOneRelationships y OneToManyRelationships igual que la propiedad de navegación con valores de colección Attributes. Para obtener más información, vea Atributos QueryEntityMetadata.

Sin embargo, también puede consultar las relaciones de entidad mediante el RelationshipDefinitions conjunto de entidades. Para obtener la SchemaName propiedad de cada relación, use una consulta como en el ejemplo siguiente.

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 acceder a las propiedades de los tipos que heredan de RelationshipMetadataBase, incluye un moldeo en la consulta como en el ejemplo siguiente para devolver solo OneToManyRelationshipMetadata EntityType.

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

Dado que las entidades devueltas se escriben como OneToManyRelationshipMetadata, puede filtrar por propiedades como ReferencedEntity para construir una consulta que devuelva solo las relaciones de entidad uno a varios para una entidad específica, como la entidad de cuenta que se muestra en la consulta siguiente:

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

Esta consulta devuelve esencialmente los mismos resultados que la consulta siguiente, que se filtra porque se incluye en la EntityMetadataOneToManyRelationships propiedad de navegación con valores de colección 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

En el ejemplo siguiente se muestra cómo recuperar un conjunto de opciones globales mediante .MetadataId

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

Ejemplo por nombre

En el ejemplo siguiente se muestra cómo recuperar una opción global establecida por nombre:

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

También puede acceder a la definición de un conjunto de opciones globales desde la propiedad de navegación de valor único GlobalOptionSet para cualquier atributo que lo utilice. Esta propiedad está disponible para todos los tipos derivados de EntityType de EnumAttributeMetadata. Para obtener más información, consulte Recuperación de 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#)

  • Last updated on