Query's uitvoeren op metagegevens via de web-API

Artikel
03/04/2017

Gepubliceerd: januari 2017

Is van toepassing op: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Aangezien Microsoft Dynamics 365 een door metagegevens gestuurde toepassing is, moeten ontwikkelaars mogelijk query's uitvoeren op de systeemmetagegevens tijdens runtime ten behoeve van aanpassing aan de wijze waarop een organisatie is geconfigureerd. Deze mogelijkheid is beschikbaar via de web-API en met behulp van de organisatieservice via het gebruik van de RetrieveMetadataChangesRequest en de klassen van de Microsoft.Xrm.Sdk.Metadata.Query-naamruimte. De web-API maakt het mogelijk query's uit te voeren op metagegevens maar biedt niet het vermogen om wijzigingen in metagegevens te detecteren vanaf een specifiek tijdstip.

In dit onderwerp

Query's uitvoeren op het entiteitstype EntityMetadata

Gebruik opsommingstypen in $filter-bewerkingen

Gebruik complexe typen in $filter-bewerkingen

Query's uitvoeren op EntityMetadata-kenmerken

Kenmerken ophalen

Query's uitvoeren op relatiemetagegevens

Query's uitvoeren op algemene optiesets

Query's uitvoeren op het entiteitstype EntityMetadata

U gebruikt dezelfde methoden als worden beschreven in Querygegevens met behulp van de web-API bij het uitvoeren van query's op EntityMetadata, met enkele variaties. Gebruik het EntityDefinitions-entiteitenreekspad om informatie op te halen over de EntityMetadata EntityType.EntityMetadata-entiteiten bevatten veel gegevens zodat u ervoor moet zorgen dat u alleen de gegevens ophaalt die u werkelijk nodig hebt. Het volgende voorbeeld toont de gegevens die worden gerouteerneerd voor alleen de eigenschappen DisplayName, IsKnowledgeManagementEnabled en EntitySetName van de metagegevens voor de entiteit Account. De waarde van de eigenschap MetadataId wordt altijd geretourneerd.

Aanvraag

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

Respons

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

U kunt elk van de EntityMetadata-eigenschappen gebruiken met $select-systeemqueryopties en u kunt $filter gebruiken op alle eigenschappen die gebruikmaken van primitieve of opsommingswaarden.

Er gelden geen limieten voor het aantal metagegevensentiteiten die worden geretourneerd in een query. Er vindt geen paging plaats. Alle overeenkomende resources worden in de eerste respons geretourneerd.

Gebruik opsommingstypen in $filter-bewerkingen

Als u metagegevensentiteiten moet filteren op basis van de waarde van een eigenschap die een opsomming gebruikt, moet u de naamruimte opnemen van de opsomming voorafgaand aan de tekenreekswaarde. Opsommingstypen worden alleen als eigenschapswaarden gebruikt in metagegevensentiteiten en complexe typen. Als u bijvoorbeeld entiteiten moet filteren op basis van de eigenschap OwnershipType, die gebruikmaakt van OwnershipTypes EnumType, kunt u de volgende $filter gebruiken om alleen entiteiten te retourneren die UserOwned zijn.

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

Gebruik complexe typen in $filter-bewerkingen

Als u metagegevensentiteiten moet filteren op basis van de waarde van een eigenschap die een complex gebruikt, moet u het pad naar het onderliggende primitieve type opnemen. Complexe typen worden alleen als eigenschapswaarden gebruikt in metagegevensentiteiten. Als u bijvoorbeeld entiteiten moet filteren op basis van de eigenschap CanCreateAttributes, die gebruikmaakt van BooleanManagedProperty ComplexType, kunt u de volgende $filter gebruiken om alleen entiteiten te retourneren die een Value van true hebben.

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

Dit patroon werkt met BooleanManagedProperty ComplexType omdat de te controleren primitieve waarde één niveau diep is. Het werkt echter niet bij eigenschappen van Label ComplexType.

Query's uitvoeren op EntityMetadata-kenmerken

U kunt query's uitvoeren op entiteitskenmerken in de context van een entiteit door de collection-valued navigatie-eigenschap Attributes uit te vouwen maar hierbij worden alleen de algemene eigenschappen opgenomen die beschikbaar zijn in de AttributeMetadata EntityType die alle kenmerken delen. Zo retourneert bijvoorbeeld de volgende query de LogicalName van de entiteit en alle uitgevouwen Attributes met een waarde AttributeType die is gelijk aan de AttributeTypeCode EnumType-waarde van 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')

Maar u kunt de OptionSet of collection-valued navigatie-eigenschappen van GlobalOptionSet die PicklistAttributeMetadata EntityType-kenmerken hebben binnen het $select-filter van deze query niet opnemen.

Als u de eigenschappen van een specifiek type kenmerk wilt ophalen, moet u de collection-valued navigatie-eigenschap Attributes converteren naar het gewenste type. De volgende query retourneert alleen de PicklistAttributeMetadata-kenmerken en omvat de LogicalName en vouwt de collection-valued navigatie-eigenschappen OptionSet en GlobalOptionSet uit

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

Notitie

Hoewel de collection-valued navigatie-eigenschappen OptionSet en GlobalOptionSet worden gedefinieerd binnen EnumAttributeMetadata EntityType, kunt u de kenmerken niet converteren naar dit type. Dit betekent dat als u wilt filteren op andere recordtypen die deze eigenschappen eveneens overnemen (zie Entity types that inherit from activitypointer), u aparte query's moet uitvoeren om op elk type te filteren.

Een ander voorbeeld hiervan is het verkrijgen van toegang tot de eigenschap Precision die beschikbaar is in de kenmerken MoneyAttributeMetadata EntityType en DecimalAttributeMetadata EntityType. Als u toegang wilt tot deze eigenschap moet u de kenmerkenverzameling converteren naar MoneyAttributeMetadata of DecimalAttributeMetadata. Een voorbeeld van het converteren naar MoneyAttributeMetadata wordt hier weergegeven.

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

Filteren op vereist niveau

De eigenschap AttributeMetadata EntityTypeRequiredLevel gebruikt een speciale AttributeRequiredLevelManagedProperty ComplexType, waarbij de eigenschap Value een AttributeRequiredLevel EnumType is. In dit geval moet u patronen die zijn in Gebruik complexe typen in $filter-bewerkingen en Gebruik opsommingstypen in $filter-bewerkingen combineren om te filteren op deze unieke eigenschap. Met de volgende query wordt gefilterd op kenmerken in de accountentiteit die ApplicationRequired zijn.

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

Kenmerken ophalen

Als u de MetadataId weet voor zowel de EntityMetadata als de AttributeMetadata, kunt u een individueel kenmerk ophalen en toegang krijgen tot de eigenschapswaarden met een query zoals de volgende. Deze query haalt de eigenschap LogicalName van het kenmerk op en vouwt tevens de collection-valued navigatie-eigenschap OptionSet uit. Overigens moet u het kenmerk converteren als een Microsoft.Dynamics.CRM.PicklistAttributeMetadata om toegang te krijgen tot de collection-valued navigatie-eigenschap OptionSet.

Aanvraag

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

Respons

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

Als u geen eigenschappen van het kenmerk nodig hebt en alleen de waarden wilt van een collection-valued navigatie-eigenschap zoals OptionsSet, kunt u die opnemen in de URL en de eigenschappen beperken met een $select-systeemquery voor een enigszins efficiëntere query. In het volgende voorbeeld wordt alleen de eigenschap Options van de OptionSet opgenomen.

Aanvraag

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

Respons

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

Query's uitvoeren op relatiemetagegevens

U kunt op dezelfde manier relatiemetagegevens ophalen in de context van een specifieke entiteit als u doet bij het uitvoeren van query's op kenmerken. Op de collection-valued navigatie-eigenschappen ManyToManyRelationships, ManyToOneRelationships en OneToManyRelationships kunnen query's worden uitgevoerd op dezelfde manier als bij de collection-valued navigatie-eigenschap Attributes.Meer informatie:Query's uitvoeren op EntityMetadata-kenmerken

Er kunnen echter ook query's worden uitgevoerd op entiteitsrelaties met de RelationshipDefinitions-entiteitset. U kunt een query zoals de volgende gebruiken om de eigenschap SchemaName voor elke relatie op te halen.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions?$select=SchemaName

De beschikbare eigenschappen bij het uitvoeren van query's op deze entiteit zijn beperkt tot de eigenschappen in het RelationshipMetadataBase EntityType Als u toegang wilt krijgen tot eigenschappen vanuit de entiteittypen die overnemen vanuit RelationshipMetadataBase, moet u een conversie als de volgende opnemen in de query om alleen OneToManyRelationshipMetadata EntityType te retourneren.

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

Aangezien de entiteiten die worden geretourneerd zijn getypeerd als OneToManyRelationshipMetadata, kunt u filteren op de eigenschappen zoals ReferencedEntity om een query te construeren waarmee alleen de één-op-veel entiteitsrelaties voor een specifieke entiteit worden geretourneerd, zoals de accountentiteit, zoals aangegeven in de volgende query:

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

Die query retourneert in essentie dezelfde resultaten als de volgende query, die wordt gefilterd omdat hij is opgenomen in de collection-valued navigatie-eigenschap EntityMetadataOneToManyRelationships van de accountentiteit. Het verschil is dat u voor de vorige query niet de MetadataId voor de accountentiteit hoeft te weten.

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

Query's uitvoeren op algemene optiesets

U kunt het GlobalOptionSetDefinitions-entiteitenreekspad gebruiken om informatie op te halen over algemene optiesets, maar dit pad biedt geen ondersteuning voor het gebruik van de $filter-systeemqueryoptie. Dus, tenzij u de MetadataId weet voor een specifieke algemene optieset, kunt u ze alleen allemaal ophalen. U kunt ook toegang krijgen tot de definitie van een algemene optieset vanuit de single-valued navigatie-eigenschap GlobalOptionSet voor elk kenmerk dat hiervan gebruikmaakt. Dit is beschikbaar voor alle Entity types that inherit from activitypointer.Meer informatie:Kenmerken ophalen

Zie ook

De web-API gebruiken met Dynamics 365-metagegevens
Metagegevens ophalen op naam of MetadataId
Entiteitsdefinities maken en bijwerken met behulp van de web-API
Entiteitsrelaties maken en bijwerken met behulp van de web-API

Microsoft Dynamics 365

Delen via

Query's uitvoeren op metagegevens via de web-API

In dit onderwerp

Query's uitvoeren op het entiteitstype EntityMetadata

Gebruik opsommingstypen in $filter-bewerkingen

Gebruik complexe typen in $filter-bewerkingen

Query's uitvoeren op EntityMetadata-kenmerken

Filteren op vereist niveau

Kenmerken ophalen

Query's uitvoeren op relatiemetagegevens

Query's uitvoeren op algemene optiesets

Zie ook

Aanvullende resources