Interroger des définitions de table à l’aide de l’API web

Étant donné que Microsoft Dataverse est une application basée sur des métadonnées, les développeurs peuvent avoir besoin d’interroger les définitions système au moment de l’exécution pour s’adapter à la configuration d’une organisation. Cette fonctionnalité utilise un style de requête RESTful.

Interroger le type d’entité EntityMetadata

Utilisez les mêmes techniques décrites dans les données de requête à l’aide de l’API web lorsque vous interrogez EntityMetadata, avec quelques variantes. Utilisez le chemin de l'ensemble d'entités EntityDefinitions pour obtenir des informations sur EntityMetadata EntityType. Les entités EntityMetadata contiennent beaucoup de données. Par conséquent, récupérez uniquement les données dont vous avez besoin. L’exemple suivant montre les données renvoyées uniquement pour les propriétés DisplayName, IsKnowledgeManagementEnabled et EntitySetName de la définition de l’entité Account. La valeur de la propriété MetadataId est toujours retournée.

Demande :

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  

Réponse :

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

Vous pouvez utiliser l’une des propriétés EntityMetadata avec les $select options de requête système. Vous pouvez utiliser $filter sur toutes les propriétés qui utilisent des valeurs primitives ou d’énumération.

Il n’existe aucune limite quant au nombre d’entités de métadonnées retournées par une requête. Il n’existe aucune pagination. La première réponse retourne toutes les ressources correspondantes.

Limiter les langues renvoyées

Lorsqu plusieurs langues sont provisionnées dans un environnement, la quantité de données renvoyées peut devenir importante. Pour optimiser les performances, limitez les étiquettes de langue retournées à l’aide du LabelLanguages paramètre avec la valeur LCID de la langue à retourner.

Les codes de langue sont des ID de paramètres régionaux composés de quatre ou cinq chiffres. Les valeurs d’ID de paramètres régionaux valides sont disponibles sur la page Tableau des ID de paramètres régionaux (LCID).

Par exemple, l’ajout de la valeur suivante limite les étiquettes de langue localisées à l’anglais : &LabelLanguages=1033.

Utilisez les types d’énumération dans les opérations $filter

Lorsque vous devez filtrer les entités de métadonnées en fonction de la valeur d’une propriété qui utilise une énumération, incluez l’espace de noms de l’énumération avant la valeur de chaîne. Les types d’énumération sont utilisés comme valeurs de propriété uniquement dans les entités de métadonnées et les types complexes. Par exemple, si vous devez filtrer des entités en fonction de la OwnershipType propriété, qui utilise l’énumération PropertyTypes, utilisez ce qui suit $filter pour renvoyer uniquement les entités qui sont UserOwned.

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

Utiliser les types complexes dans les opérations $filter

Lorsque vous devez filtrer les entités de métadonnées en fonction de la valeur d’une propriété qui utilise un type complexe, incluez le chemin d’accès au type primitif sous-jacent. Les types complexes sont utilisés comme valeurs de propriété uniquement dans les entités de métadonnées. Par exemple, si vous devez filtrer des entités basées sur la propriété CanCreateAttributes, qui utilise le type complexe BooleanManagedProperty, utilisez les éléments suivants $filter pour renvoyer uniquement les entités qui ont une valeur de Value de true.

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

Ce modèle fonctionne avec le type BooleanManagedProperty ComplexType, car la valeur primitive à vérifier se situe à un niveau en profondeur. Toutefois, ce modèle ne fonctionne pas sur les propriétés de Label ComplexType.

Interroger les attributs de EntityMetadata

Vous pouvez interroger des attributs d’entité dans le contexte d’une entité en développant la Attributes propriété de navigation à valeur de collection. Cette approche inclut uniquement les propriétés communes disponibles dans l’EntityType AttributeMetadata que tous les attributs partagent. Par exemple, la requête suivante retourne l’entité LogicalName et tous les attributs développés qui ont une AttributeType valeur égale à la valeur 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')  

Mais vous ne pouvez pas inclure les propriétés de navigation à valeur de collection OptionSet ou GlobalOptionSet que possèdent les attributs PicklistAttributeMetadata EntityType dans le filtre $select de cette requête.

Pour récupérer les propriétés d’un type spécifique d’attribut, convertissez la Attributes propriété de navigation à valeur de collection sur le type souhaité. La requête suivante retourne uniquement les attributs PicklistAttributeMetadata EntityType . Il inclut LogicalName et développe les propriétés de navigation OptionSet et GlobalOptionSet à valeur de collection.

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

Un autre exemple de cette limitation consiste à accéder à la Precision propriété disponible dans les attributs MoneyAttributeMetadata EntityType et DecimalAttributeMetadata EntityType . Pour accéder à cette propriété, vous devez convertir la collection d’attributs en MoneyAttributeMetadata EntityType ou DecimalAttributeMetadata EntityType. Un exemple de conversion vers MoneyAttributeMetadata est illustré ici.

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

Filtrer par niveau requis

La propriété AttributeMetadata EntityTypeRequiredLevel utilise un AttributeRequiredLevelManagedProperty ComplexType spécial où la propriété Value est un AttributeRequiredLevel EnumType. Pour filtrer par cette propriété unique, combinez des modèles trouvés dans Utiliser des types complexes dans $filter opérations et utiliser des types d’énumération dans $filter opérations. La requête suivante filtre ces attributs dans l’entité de compte qui sont ApplicationRequired.

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

Récupérer des attributs

Lorsque vous connaissez la valeur pour à la fois MetadataId et AttributeMetadata, ou seulement pour EntityMetadata ou LogicalName, vous pouvez récupérer un attribut particulier et accéder aux valeurs des propriétés à l’aide d’une requête telle que l’exemple suivant. Cette requête récupère la LogicalName propriété de l’attribut et étend la OptionSet propriété de navigation à valeur de collection. Pour accéder à la propriété de navigation à valeur de collection OptionSet, vous devez effectuer un cast de l’attribut en Microsoft.Dynamics.CRM.PicklistAttributeMetadata.

Demande :

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  

Réponse :

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 vous n’avez pas besoin de propriétés de l’attribut et souhaitez uniquement les valeurs d’une propriété de navigation à valeur de collection, par OptionSetexemple, incluez cette propriété dans l’URL et limitez les propriétés à l’aide d’une $select option de requête système pour une requête plus efficace. Dans l’exemple suivant, seule la Options propriété du fichier OptionSet est incluse.

Demande :

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  

Réponse :

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

Métadonnées de relation de requête

Vous pouvez récupérer des métadonnées de relation dans le contexte d’une entité donnée, comme la façon dont vous interrogez des attributs. Vous pouvez interroger les propriétés de navigation à valeur de collection ManyToManyRelationships, ManyToOneRelationships et OneToManyRelationships, tout comme la propriété de navigation à valeur de collection Attributes. Pour plus d’informations, consultez Attributs QueryEntityMetadata.

Toutefois, vous pouvez également interroger des relations d’entité à l’aide de l’ensemble d’entités RelationshipDefinitions . Pour obtenir la SchemaName propriété pour chaque relation, utilisez une requête comme l’exemple suivant.

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

Les propriétés disponibles lors de l’interrogation de cet ensemble d’entités se limitent à celles présentes dans le type RelationshipMetadataBase EntityType. Pour accéder aux propriétés des types d’entités qui héritent de RelationshipMetadataBase, effectuez un transtypage dans la requête comme dans l’exemple suivant pour renvoyer uniquement OneToManyRelationshipMetadata EntityType.

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

Étant donné que les entités retournées sont typées OneToManyRelationshipMetadata, vous pouvez filtrer par des propriétés telles que ReferencedEntity pour construire une requête qui retourne uniquement les relations d’entité un-à-plusieurs pour une entité spécifique, comme l’entité compte indiquée dans la requête suivante :

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

Cette requête retourne essentiellement les mêmes résultats que la requête suivante, qui est filtrée, car elle est incluse dans la EntityMetadataOneToManyRelationships propriété de navigation à valeur de collection de l’entité de compte. La différence est que pour la requête précédente, il n’est pas nécessaire de connaître le MetadataId de l’entité de compte.

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

Rechercher des ensembles d’options globales

Vous pouvez utiliser le chemin d’accès de l’ensemble d’entités GlobalOptionSetDefinitions pour récupérer des informations sur les groupes d’options globaux, mais ce chemin ne prend pas en charge l’utilisation de l’option de requête système $filter. Ainsi, vous ne pouvez récupérer qu’un seul groupe d’options global soit par MetadataId, soit par le nom unique.

Exemple : par MetadataId

L’exemple suivant montre comment récupérer un ensemble d'options globales en utilisant le MetadataId.

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

Exemple par nom

L’exemple suivant montre comment récupérer une option globale définie par nom :

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

Vous pouvez également accéder à la définition d'un ensemble d'options global à partir de la propriété de navigation à valeur unique GlobalOptionSet d'un attribut qui l'utilise. Cette propriété est disponible pour tous les EnumAttributeMetadata EntityType Derived Types. Pour plus d’informations, consultez Récupérer des attributs.

Voir aussi

Utiliser l’API web avec les métadonnées Dataverse
Récupérer des métadonnées par nom ou MetadataId
Entités de métadonnées et attributs à l’aide de l’API web
Relations d’entités de métadonnées à l’aide de l’API web
Exemple d’opérations de schéma de table de l’API web
Exemple d’opérations de schéma de table de l’API web (C#)