Interroger les métadonnées à l'aide de l'API Web

Article
03/04/2017

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Comme Microsoft Dynamics 365 est une application pilotée par des métadonnées, les développeurs devront peut-être interroger les métadonnées du système au moment de l'exécution pour s'adapter à la façon dont une organisation a été configurée. Cette fonctionnalité est disponible via l'API Web et le service d'organisation en utilisant RetrieveMetadataChangesRequest et les classes de l'espace de noms Microsoft.Xrm.Sdk.Metadata.Query. L'API Web permet d'interroger les métadonnées, mais ne permet pas de détecter les modifications apportées aux métadonnées à partir d'un moment donné.

Contenu de la rubrique

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

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

Utiliser les types complexes dans les opérations $filter

Requête portant sur les attributs EntityMetadata

Récupération des attributs

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

Requête portant sur les groupes d'options globaux

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 présente les données retournées pour les propriétés DisplayName, IsKnowledgeManagementEnabled et EntitySetName des métadonnées de l'entité Account. La valeur de la propriété MetadataId est toujours retournée.

Demande

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=DisplayName,IsKnowledgeManagementEnabled,EntitySetName&$filter=SchemaName eq 'Account' 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": "cc_WebAPI_ServiceURI/$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 cc_WebAPI_ServiceURI/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 cc_WebAPI_ServiceURI/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 Attributes développés dont la valeur AttributeType est égale à la valeur AttributeTypeCode EnumType de Picklist.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)?$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 et contient le LogicalName. Elle développe également les propriétés de navigation à valeur de collection OptionSet et GlobalOptionSet

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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 Entity types that inherit from activitypointer), 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 ou DecimalAttributeMetadata. Un exemple de cast vers MoneyAttributeMetadata est illustré ici.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.MoneyAttributeMetadata?$select=LogicalName,Precision

Filtrage par niveau requis

La propriété AttributeMetadata EntityTypeRequiredLevel utilise un AttributeRequiredLevelManagedProperty ComplexType spécial lorsque la propriété Value est un AttributeRequiredLevel EnumType. Dans ce cas, vous devez combiner les modèles disponibles dans Utiliser les types complexes dans les opérations $filter et Utiliser les types d'énumération dans les opérations $filter pour filtrer en fonction de cette propriété unique. La requête suivante filtre les attributs de l'entité de compte de type ApplicationRequired.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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 cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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": "cc_WebAPI_ServiceURI/$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": "cc_WebAPI_ServiceURI/$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 cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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": "cc_WebAPI_ServiceURI/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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 :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 cc_WebAPI_ServiceURI/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 cc_WebAPI_ServiceURI/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 cc_WebAPI_ServiceURI/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 cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/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. Par conséquent, sauf si vous connaissez le MetadataId d'un groupe d'options global spécifique, vous devez tous les récupérer. 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. Elle est disponible pour tous les Entity types that inherit from activitypointer.Pour plus d'informations :Récupération des attributs

Voir aussi

Utiliser l'API Web avec les métadonnées Dynamics 365
Récupérer des métadonnées par nom ou MetadataId
Créer et mettre à jour les définitions d'entité à l’aide de l'API Web
Créer et mettre à jour les relations d'entité à l’aide de l'API Web

Microsoft Dynamics 365

Partager via

Interroger les métadonnées à l'aide de l'API Web

Contenu de la rubrique

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

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

Utiliser les types complexes dans les opérations $filter

Requête portant sur les attributs EntityMetadata

Filtrage par niveau requis

Récupération des attributs

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

Requête portant sur les groupes d'options globaux

Voir aussi

Ressources supplémentaires