Requête des définitions de table à l'aide de l'API Web
Notes
Vous n’êtes pas sûr de l’entité par rapport à la table ? Voir Développeurs : Comprendre la terminologie dans Microsoft Dataverse.
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.
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, à quelques variations près. 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 pour l'entité Account. La valeur de la propriété MetadataId est toujours retournée.
Demande
GET [Organization URI]/api/data/v9.0/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.0/$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.
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 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.0/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 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.0/EntityDefinitions?$select=LogicalName&$filter=CanCreateAttributes/Value eq true
Ce modèle fonctionne avec BooleanManagedProperty ComplexType, car la valeur primitive à activer se situe un niveau plus bas. Toutefois, il ne fonctionne pas sur les propriétés de Label 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 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 de Picklist.
GET [Organization URI]/api/data/v9.0/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 des 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.0/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 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 consiste à accéder à la propriété Precision disponible dans les attributs MoneyAttributeMetadata EntityType et DecimalAttributeMetadata EntityType. Pour accéder à cette propriété, vous devez effectuer un cast de la collection d'attributs en tant que MoneyAttributeMetadata EntityType ou DecimalAttributeMetadata EntityType. Un exemple de cast vers MoneyAttributeMetadata est illustré ici.
GET [Organization URI]/api/data/v9.0/EntityDefinitions(LogicalName='account')/Attributes/Microsoft.Dynamics.CRM.MoneyAttributeMetadata?$select=LogicalName,Precision
Filtrage par niveau requis
La propriété AttributeMetadata EntityType RequiredLevel utilise un AttributeRequiredLevelManagedProperty ComplexType spécial lorsque la propriété Value est un 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.0/EntityDefinitions(LogicalName='account')/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'
Récupération des attributs
Lorsque vous connaissez le MetadataId de EntityMetadata et de AttributeMetadata, 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. Notez que vous devez effectuer un cast de l'attribut en tant que Microsoft.Dynamics.CRM.PicklistAttributeMetadata pour accéder à la propriété de navigation à valeur de collection OptionSet.
Demande
GET [Organization URI]/api/data/v9.0/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.0/$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.0/$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 seules les valeurs d'une propriété de navigation à valeur de collection telle que OptionsSet sont requises, vous pouvez l'inclure dans l'URL et limiter les propriétés avec une option de requête système $select pour obtenir une requête un peu plus efficace. Dans l'exemple suivant, seule la propriété Options de OptionSet est incluse.
Demande
GET [Organization URI]/api/data/v9.0/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.0/$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.0/RelationshipDefinitions?$select=SchemaName
Les propriétés disponibles lors de l'interrogation de cet ensemble d'entités se limitent à celles présentes dans 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 OneToManyRelationshipMetadata EntityType.
GET [Organization URI]/api/data/v9.0/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.0/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.0/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.0/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.0/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
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é).
Commentaires
Envoyer et afficher des commentaires pour