Partager via

Requête des définitions de table à l’aide de l’API Web

  • Article

Parce que Microsoft Dataverse est une application pilotée par 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 façon dont une organisation a été configurée. Cette fonctionnalité utilise un style de requête RESTful.

Notes

Vous pouvez également construire une requête en utilisant un style basé sur l’objet à l’aide du EntityQueryExpression ComplexType avec la RetrieveMetadataChanges Function. Cette fonction permet de capturer les modifications apportées aux définitions de table entre deux périodes et de renvoyer un ensemble limité de définitions décrites par une requête que vous spécifiez. Pour plus d’informations : Interroger les définitions de schéma

Requête portant sur le type d’entité EntityMetadata

Vous utiliserez les mêmes techniques décrites dans Interroger les données à l’aide de l’API Web lorsque vous interrogez EntityMetadata, avec quelques variantes. Utilisez le chemin d’accès de l’ensemble d’entités EntityDefinitions pour récupérer des informations sur EntityMetadata EntityType. Les entités EntityMetadata contiennent une grande quantité de données ; vous devez donc veiller à récupérer uniquement les données nécessaires. 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 les propriétés EntityMetadata avec les options de requête système $select et vous pouvez utiliser $filter sur les propriétés qui utilisent des valeurs primitives ou d’énumération.

Le nombre d’entités de métadonnées qui seront retournées dans une requête est illimité. Il n’existe aucune pagination. Toutes les ressources correspondantes seront retournées dans la première réponse.

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 de meilleures performances, limitez les Étiquettes de langues renvoyées à l’aide du paramètre LabelLanguages avec la valeur LCID de la langue que vous souhaitez renvoyer.

Les codes de langue sont des ID de paramètres régionaux à 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, si vous ajoutez ce qui suit, les Étiquettes de langue localisées seront limités à l’anglais : &LabelLanguages=1033.

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

Lorsque vous devez filtrer des entités de métadonnées en fonction de la valeur d’une propriété qui utilise une énumération, vous devez inclure l’espace de noms de l’énumération avant la valeur de la 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 propriété OwnershipType, qui utilise le type OwnershipTypes Enumtype, vous pouvez utiliser l’élément $filter suivant pour retourner uniquement les entités de type 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 des entités de métadonnées en fonction de la valeur d’une propriété qui utilise un type complexe, vous devez inclure 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 en fonction de la propriété CanCreateAttributes qui utilise le type BooleanManagedProperty ComplexType, vous pouvez utiliser l’élément $filter suivant pour retourner uniquement les entités dont Value est 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 à activer se situe un niveau plus bas. Cependant, cela ne fonctionne pas sur les propriétés de type Étiquette ComplexType.

Requête portant sur les attributs EntityMetadata

Vous pouvez interroger les attributs d’entité dans le contexte d’une entité en développant la propriété de navigation à valeur de collection Attributes , mais elle inclut uniquement les propriétés communes disponibles dans le AttributeMetadata EntityType que tous les attributs partagent. Par exemple, la requête suivante retourne le LogicalName de l’entité et tous les attributs développés dont la valeur AttributeType est égale à la valeur AttributeTypeCode EnumType dePicklist.

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 d’attribut spécifique, vous devez effectuer un cast de la propriété de navigation à valeur de collection Attributes vers le type de votre choix. La requête suivante retourne uniquement les attributs PicklistAttributeMetadata EntityType et contient le LogicalName. Elle développe également les propriétés de navigation à valeur de collection OptionSet et GlobalOptionSet.

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

Notes

Bien que les propriétés de navigation à valeur de collection OptionSet et GlobalOptionSet soient définies dans le type EnumAttributeMetadata EntityType, vous ne pouvez pas effectuer un cast des attributs vers ce type. Cela signifie que si vous voulez filtrer d’autres types qui héritent également de ces propriétés (voir Types d’entité qui héritent de EnumAttributeMetadata), vous devez exécuter des requêtes distinctes pour filtrer chaque type.

Un autre exemple de ceci est l’accès à la propriété Precision 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 cast vers MoneyAttributeMetadata est illustré ici.

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

Filtrage par niveau requis

La propriété AttributeMetadata EntityType RequiredLevel utilise un type AttributeRequiredLevelManagedProperty ComplexType spécial où la propriété Value est un type AttributeRequiredLevel EnumType. Dans ce cas, vous devez associer des critères qui se trouvent dans Utiliser les types complexes dans les opérations $filter et Utiliser les types d’énumération dans les opérations $filter pour filtrer par cette propriété seule. La requête suivante filtre les attributs de l’entité de compte de type 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ération des attributs

Quand vous connaissez le MetadataId de EntityMetadata et AttributeMetadata, ou la valeur LogicalName de l’un ou l’autre, vous pouvez récupérer un attribut individuel et accéder aux valeurs de propriété à l’aide de la requête suivante. Cette requête récupère la propriété LogicalName de l’attribut et développe la propriété de navigation à valeur de collection OptionSet. Pour accéder à cette de navigation à valeur de collection OptionSet, vous devez effectuer un cast de l’attribut en tant que 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 les propriétés de l’attribut ne sont pas nécessaires et que seules les valeurs d’une propriété de navigation à valeur de collection telle que OptionsSet, vous pouvez l’inclure dans l’URL et limiter les propriétés avec une option de requête système $selectpour que la requête soit plus efficace. Dans l’exemple suivant, seule la propriété Options de 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"  
}

Requête portant sur les métadonnées de relation

Vous pouvez récupérer des métadonnées de relation dans le contexte d’une entité donnée de la même manière que vous pouvez interroger des attributs. Les propriétés de navigation à valeur de collection ManyToManyRelationships, ManyToOneRelationships et OneToManyRelationships peuvent être interrogées comme la propriété de navigation à valeur de collection Attributes. Pour plus d’informations, voir Requête portant sur les attributs EntityMetadata

Toutefois, les relations d’entité peuvent également être interrogées à l’aide de l’ensemble d’entités RelationshipDefinitions. Vous pouvez utiliser la requête suivante pour obtenir la propriété SchemaName pour chaque relation.

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 à partir des types d’entités qui héritent de RelationshipMetadataBase, vous devez inclure un cast dans la requête suivante pour retourner uniquement le type OneToManyRelationshipMetadata EntityType.

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

Comme les entités retournées sont typées en tant que OneToManyRelationshipMetadata, vous pouvez filtrer les propriétés telles que ReferencedEntity pour créer une requête qui retourne uniquement les relations d’entité de type un-à-plusieurs pour une entité spécifique, telle que l’entité de compte, comme illustré 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 propriété de navigation à valeur de collection EntityMetadataOneToManyRelationships 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

Requête portant sur les groupes d’options globaux

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 ou le nom unique.

Exemple : par MetadataId

L’exemple suivant illustre la récupération d’un groupe d’options global à l’aide de l’extension MetadataId.

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

Exemple par nom

L’exemple suivant illustre la récupération d’un groupe d’options global par nom :

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

Vous pouvez également accéder à la définition d’un groupe d’options global à partir de la propriété de navigation à valeur de collection GlobalOptionSet d’un attribut qui l’utilise. Cela est possible pour tous les Types dérivés par EntityType d’EnumAttributeMetadata. Pour plus d’informations : Récupération 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#)

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).