Query sui metadati tramite la Web API

Articolo
03/03/2017

Data di pubblicazione: gennaio 2017

Si applica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Poiché Microsoft Dynamics 365 è un'applicazione basata su metadati, gli sviluppatori possono avere l'esigenza di eseguire query sui metadati di sistema al runtime per adattarsi a come un'organizzazione è stata configurata. Questa funzionalità è disponibile nella Web API e nel servizio dell'organizzazione utilizzando RetrieveMetadataChangesRequest e le classi dello spazio dei nomi Microsoft.Xrm.Sdk.Metadata.Query. La Web API consente di eseguire query sui metadati ma non è in grado di rilevare le modifiche ai metadati a partire da una specifica data e ora.

In questo argomento

Esecuzione di query sul tipo di entità EntityMetadata

Usare tipi enum nelle operazioni $filter

Usare tipi complessi nelle operazioni $filter

Esecuzione di query sugli attributi di EntityMetadata

Recupero di attributi

Esecuzione di query sui metadati di relazione

Esecuzione di query su set di opzioni globali

Esecuzione di query sul tipo di entità EntityMetadata

Andranno utilizzate le stesse tecniche descritte in Query di dati tramite l'API Web quando si eseguono query su EntityMetadata, con poche variazioni. Utilizzare il percorso del set di entità EntityDefinitions per recuperare informazioni su EntityMetadata EntityType. Le entità EntityMetadata contengono molti dati, quindi è importante fare attenzione a recuperare solo i dati necessari. L'esempio seguente illustra i dati restituiti solo per le proprietà DisplayName, IsKnowledgeManagementEnabled e EntitySetName dei metadati dell'entità Account. Il valore della proprietà MetadataId viene sempre restituito.

Richiesta

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

Risposta

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

È possibile utilizzare qualsiasi proprietà EntityMetadata con le opzioni di query di sistema $select ed è possibile utilizzare $filter con qualsiasi proprietà che utilizza valori primitivi o di enumerazione.

Non esistono limiti al numero di entità metadati che vengono restituite in una query. Non esiste paging. Tutte le risorse corrispondenti vengono restituite nella prima risposta.

Usare tipi enum nelle operazioni $filter

Quando è necessario filtrare le entità metadati in base al valore di una proprietà che utilizza una enumerazione, è necessario includere lo spazio dei nomi dell'enumerazione prima del valore stringa. I tipi enum vengono utilizzati come valori di proprietà solo nelle entità metadati e nei tipi complessi. Ad esempio, per filtrare le entità in base alla proprietà OwnershipType, che utilizza OwnershipTypes EnumType, è possibile utilizzare il seguente $filter per la restituzione delle sole entita UserOwned.

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=OwnershipType eq Microsoft.Dynamics.CRM.OwnershipTypes'UserOwned'

Usare tipi complessi nelle operazioni $filter

Quando è necessario filtrare le entità metadati in base al valore di una proprietà che utilizza un tipo complesso, è necessario includere il percorso del tipo primitivo sottostante. I tipi complessi vengono utilizzati come valori di proprietà solo nelle entità metadati. Ad esempio, per filtrare le entità in base alla proprietà CanCreateAttributes, che utilizza BooleanManagedProperty ComplexType, è possibile utilizzare il seguente $filter per la restituzione delle sole entita che hanno Value uguale a true.

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=CanCreateAttributes/Value eq true

Questo modello funziona con BooleanManagedProperty ComplexType perché il valore primitivo da controllare ha la profondità di un livello. Tuttavia, non funziona con le proprietà di Label ComplexType.

Esecuzione di query sugli attributi di EntityMetadata

È possibile eseguire una query sugli attributi nel contesto di un'entità espandendo la proprietà di navigazione con valori di raccolta Attributes ma saranno incluse solo le proprietà comuni disponibili nell'AttributeMetadata EntityType condiviso da tutti gli attributi. Ad esempio la query seguente restituirà il LogicalName dell'entità e tutti gli Attributes espansi che hanno un valore AttributeType uguale al valore AttributeTypeCode EnumType di 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')

Ma non è possibile includere le proprietà di navigazione con valori di raccolta OptionSet o GlobalOptionSet che gli attributi PicklistAttributeMetadata EntityType hanno nel filtro $select della query.

Per recuperare le proprietà di un determinato tipo di attributo è necessario eseguire il cast della proprietà di navigazione con valori di raccolta Attributes al tipo desiderato. La seguente query restituirà solo gli attributi PicklistAttributeMetadata e includerà il LogicalName oltre a espandere le proprietà di navigazione con valori di raccolta OptionSet e GlobalOptionSet.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet,GlobalOptionSet

Nota

Nonostante il fatto che le proprietà di navigazione con valori di raccolta OptionSet e GlobalOptionSet siano definite in EnumAttributeMetadata EntityType, non è possibile eseguire il cast degli attributi a questo tipo. Questo significa che se si desidera filtrare in base ad altri tipi che anche ereditano queste proprietà (vedere Entity types that inherit from activitypointer), è necessario eseguire query distinte per filtrare in base a ogni tipo.

Un altro esempio di ciò è l'accesso alla proprietà Precision disponibile negli attributi MoneyAttributeMetadata EntityType e DecimalAttributeMetadata EntityType. Per accedere alla proprietà è necessario eseguire il cast della raccolta di attributi come MoneyAttributeMetadata o DecimalAttributeMetadata. Un esempio che mostra il cast a MoneyAttributeMetadata è indicato di seguito.

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

Filtro in base al livello richiesto

La proprietà RequiredLevel di AttributeMetadata EntityType utilizza uno speciale AttributeRequiredLevelManagedProperty ComplexType dove la proprietà Value è AttributeRequiredLevel EnumType. In questo caso è necessario combinare i modelli disponibili in Usare tipi complessi nelle operazioni $filter e Usare tipi enum nelle operazioni $filter per filtrare in base a questa proprietà univoca. La seguente query filtrerà quegli attributi nell'entità account che sono ApplicationRequired.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'

Recupero di attributi

Quando si conosce il MetadataId sia per EntityMetadata che per AttributeMetadata, è possibile recuperare un solo attributo e accedere ai valori della proprietà mediante una query come la seguente. La query recupera la proprietà LogicalName dell'attributo ed espande la proprietà di navigazione con valori di raccolta OptionSet. Si noti che è necessario eseguire il cast dell'attributo come Microsoft.Dynamics.CRM.PicklistAttributeMetadata per accedere alla proprietà di navigazione con valori di raccolta OptionSet.

Richiesta

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

Risposta

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

Se non sono necessarie proprietà di un attributo e si desiderano solo i valori di una proprietà di navigazione con valori di raccolta come OptionsSet, è possibile includerla nell'URL e limitare le proprietà con un'opzione query di sistema $select per una query più efficiente. Nel seguente esempio solo la proprietà Options di OptionSet è inclusa.

Richiesta

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

Risposta

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

Esecuzione di query sui metadati di relazione

È possibile recuperare i metadati di relazione nel contesto di un'entità specificata in modo molto simile a come si eseguono query sugli attributi. È possibile eseguire query sulle proprietà di navigazione con valori di raccolta ManyToManyRelationships, ManyToOneRelationships e OneToManyRelationships esattamente come per la proprietà di navigazione con valori di raccolta Attributes.Ulteriori informazioni:Esecuzione di query sugli attributi di EntityMetadata

Tuttavia, le relazioni di entità possono essere sottoposte a query anche utilizzando il set di entità RelationshipDefinitions. È possibile utilizzare una query come la seguente per ottenere la proprietà SchemaName per ogni relazione.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions?$select=SchemaName

Le proprietà disponibili per l'esecuzione di query su questo set di entità sono limitate a quelle in RelationshipMetadataBase EntityType. Per accedere alle proprietà dei tipi di entità che ereditano da RelationshipMetadataBase è necessario includere un cast nella query, come il seguente, per ottenere la sola restituzione di OneToManyRelationshipMetadata EntityType.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName

Poiché le entità restituite sono tipizzate come OneToManyRelationshipMetadata, è possibile filtrare in base alle proprietà come ReferencedEntity per costruire una query che restituisca solo relazioni di entità uno-a-molti per un'entità specifica come l'entità account, come illustrato nella query seguente:

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName&$filter=ReferencedEntity eq 'account'

La query restituirà essenzialmente gli stessi risultati della query seguente, che è filtrata perché è inclusa nella proprietà di navigazione con valori di raccolta EntityMetadataOneToManyRelationships dell'entità account. La differenza sta nel fatto che per la query precedente non è necessario conoscere il MetadataId per l'entità account.

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/OneToManyRelationships?$select=SchemaName

Esecuzione di query su set di opzioni globali

È possibile utilizzare il percorso del set di entità GlobalOptionSetDefinitions per recuperare informazioni sui set di opzioni globali, ma questo percorso non supporta l'utilizzo dell'opzione query di sistema $filter. Pertanto, a meno che non sia disponibile il MetadataId per un set di opzioni globali specifico, è possibile solo recuperarli tutti. È inoltre possibile accedere alla definizione di un set di opzioni globali dalla proprietà di navigazione a valore singolo GlobalOptionSet per qualsiasi attributo che lo utilizza. Questo è disponibile per tutti i Entity types that inherit from activitypointer.Ulteriori informazioni:Recupero di attributi

Vedere anche

Utilizzare l'API Web con i metadati di Dynamics 365
Recuperare i metadati per nome o MetadataId
Creare e aggiornare definizioni di entità tramite la Web API
Creare e aggiornare relazioni di entità tramite l'API Web

Microsoft Dynamics 365

Condividi tramite

Query sui metadati tramite la Web API

In questo argomento

Esecuzione di query sul tipo di entità EntityMetadata

Usare tipi enum nelle operazioni $filter

Usare tipi complessi nelle operazioni $filter

Esecuzione di query sugli attributi di EntityMetadata

Filtro in base al livello richiesto

Recupero di attributi

Esecuzione di query sui metadati di relazione

Esecuzione di query su set di opzioni globali

Vedere anche

Risorse aggiuntive