Forespørg på metadata ved hjælp af Web-API'en

Artikel
03/03/2017

Udgivet: januar 2017

Gælder for: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Da Microsoft Dynamics 365 er et metadatabaseret program, skal udviklere muligvis forespørge, at systemets metadata på kørselstidspunktet tilpasser sig til, hvordan en organisation er blevet konfigureret. Denne funktion er tilgængelig ved hjælp af Web API'en samt organisationstjenesten ved brug af RetrieveMetadataChangesRequest og klasserne for Microsoft.Xrm.Sdk.Metadata.Query navneområdet. Web API'en giver mulighed for at forespørge metadata, men giver ikke mulighed for at registrere ændringer af metadata fra et givet tidspunkt.

Dette emne indeholder

Forespørgsel af objekttypen EntityMetadata

Bruge enum-typer i $filter-operationer

Bruge komplekse typer i $filter-operationer

Forespørger EntityMetadata-attributter

Hentning af attributter

Forespørge metadata for relation

Forespørge globale OptionSets

Forespørgsel af objekttypen EntityMetadata

Du skal bruge de samme metoder, der er beskrevet i Forespørg på data ved hjælp af Web-API'en, når du forespørger på EntityMetadata, med et par variationer. Brug EntityDefinitions-objektsætstien til at hente oplysninger om EntityMetadata EntityType.EntityMetadata-objekter indeholder en masse data, så skal du være omhyggelig med at kun at hente de data, du har brug for. Følgende eksempel viser de data, der returneres for kun DisplayName, IsKnowledgeManagementEnabled og EntitySetName-egenskaber for metadataene for Account-objektet.MetadataId-egenskabsværdien returneres altid.

Anmodning

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

Svar

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

Du kan bruge alle EntityMetadata-egenskaber med $select-systemforespørgselsindstillinger, og du kan bruge $filter på egenskaber, som bruger primitive værdier eller fasttekstværdier.

Der er ingen begrænsning på antallet af metadataobjekter, der returneres i en forespørgsel. Der er ingen sideopdeling. Alle tilsvarende ressourcer returneres i det første svar.

Bruge enum-typer i $filter-operationer

Hvis du skal filtrere metadataobjekter baseret på værdien af en egenskab, der bruger en optælling, skal du medtage optællingens navneområde før strengværdien. Enum-typer bruges kun som egenskabsværdier i metadataobjekter og komplekse typer. Hvis du f.eks. vil filtrere objekter baseret på OwnershipType-egenskaben, der bruger OwnershipTypes EnumType, kan du bruge følgende $filter til at returnere de objekter, der er UserOwned.

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

Bruge komplekse typer i $filter-operationer

Hvis du skal filtrere metadataobjekter baseret på værdien af en egenskab, der bruger en kompleks type, skal du medtage stien til den underliggende primitive type. Komplekse typer bruges kun som egenskabsværdier i metadataobjekter. Hvis du f.eks. skal filtrere objekter baseret på CanCreateAttributes-egenskaben, der bruger BooleanManagedProperty ComplexType, kan du bruge følgende $filter til kun at returnere de objekter, som har en Value for true.

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

Dette mønster fungerer sammen med BooleanManagedProperty ComplexType, da den primitive værdi, der skal kontrolleres, er ét niveau dybt. Dette virker dog ikke på egenskaberne for Label ComplexType.

Forespørger EntityMetadata-attributter

Du kan forespørge objektattributter i forbindelse med et objekt ved at udvide Attributes-navigationsegenskaben med gruppeværdi, men dette vil kun indeholde de almindelige egenskaber, der er tilgængelige i AttributeMetadata EntityType, som alle attributter deler. Følgende forespørgsel returnerer f.eks. LogicalName for objektet og alle de udvidede Attributes, som har en AttributeType-værdi lig med AttributeTypeCode EnumType-værdien af 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')

Men du kan ikke medtage OptionSet eller GlobalOptionSet-navigationsegenskaben med gruppeværdi, som PicklistAttributeMetadata EntityType-attributter har inden for $select-filtret for denne forespørgsel.

For at hente egenskaberne for en bestemt type attribut skal du konvertere Attributes-navigationsegenskaben med gruppeværdi til den ønskede type. Følgende forespørgsel returnerer kun PicklistAttributeMetadata-attributterne og omfatter LogicalName samt udvidelse af OptionSet og GlobalOptionSet-navigationsegenskaberne for gruppeværdi

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

Bemærk

Selv om OptionSet og GlobalOptionSet-navigationsegenskaberne for gruppeværdi er defineret i EnumAttributeMetadata EntityType, kan du ikke konverteres attributterne til denne type. Det betyder, at hvis du vil filtrere på andre typer, der også arver disse egenskaber (se Entity types that inherit from activitypointer), skal du udføre separate forespørgsler for at filtrere for hver type.

Et andet eksempel på dette er at få adgang til Precision-egenskaben, der er tilgængelige i MoneyAttributeMetadata EntityType og DecimalAttributeMetadata EntityType-attributter. For at få adgang til denne egenskab skal du konvertere samlingen af attributter som enten MoneyAttributeMetadata eller DecimalAttributeMetadata. Et eksempel, der viser konvertering til MoneyAttributeMetadata, er vist her.

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

Filtrering efter krævet niveau

AttributeMetadata EntityTypeRequiredLevel-egenskaben bruger en særlig AttributeRequiredLevelManagedProperty ComplexType, hvor Value-egenskaben er en AttributeRequiredLevel EnumType. I dette tilfælde skal du kombinere mønstre, der er fundet i Bruge komplekse typer i $filter-operationer og Bruge enum-typer i $filter-operationer for at filtrere efter denne unikke egenskab. Følgende forespørgsel filtrerer de attributter i firmaobjektet, der er ApplicationRequired.

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

Hentning af attributter

Når du kender MetadataId for både EntityMetadata og AttributeMetadata, kan du hente en enkelt attribut og få adgang til de egenskabsværdier, der bruger en forespørgsel som følgende. Denne forespørgsel henter LogicalName-egenskaben for attributten og udvider OptionSet-navigationsegenskaben for gruppeværdi. Bemærk, at du skal konvertere attributten som en Microsoft.Dynamics.CRM.PicklistAttributeMetadata for at få adgang til OptionSet-navigationsegenskaben for gruppeværdi.

Anmodning

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

Svar

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

Hvis du ikke kræver nogen egenskaber af attributten og kun vil have værdierne for en navigationsegenskab for gruppeværdi, f.eks. OptionsSet, kan du medtage den i URL og begrænse egenskaber med en $select-systemforespørgselsindstilling for en lidt mere effektiv forespørgsel. I det følgende eksempel er kun Options-egenskaben for OptionSet er inkluderet.

Anmodning

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

Svar

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

Forespørge metadata for relation

Du kan hente metadata for relation i forbindelse med et givent objekt på næsten samme måde, som kan du forespørge attributter.ManyToManyRelationships, ManyToOneRelationships og OneToManyRelationships-navigationsegenskaben for gruppeværdi kan forespørges på sammen måde som Attributes-navigationsegenskaben for gruppeværdi.Flere oplysninger:Forespørger EntityMetadata-attributter

Objektrelationer kan dog også forespørges ved hjælp af RelationshipDefinitions-objektsættet. Du kan bruge en forespørgsel som følgende for at få SchemaName-egenskaben for hver relation.

GET cc_WebAPI_ServiceURI/RelationshipDefinitions?$select=SchemaName

De egenskaber, der er tilgængelige, når du forespørger om dette objektsæt, er begrænset til dem i RelationshipMetadataBase EntityType. For at få adgang til egenskaber fra objekttyper, der arver fra RelationshipMetadataBase, skal du medtage en konvertering i forespørgslen som følgende for kun at returnere OneToManyRelationshipMetadata EntityType.

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

Da de returnerede objekter er angivet som OneToManyRelationshipMetadata, kan du filtrere på egenskaberne som ReferencedEntity for at oprette en forespørgsel for kun at returnere en-til-mange-objektrelationer for et bestemt objekt, f.eks. firmaobjektet som vist i følgende forespørgsel:

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

Forespørgslen returnerer stort set de samme resultater som følgende forespørgsel, som er filtreret, da den indgår i EntityMetadataOneToManyRelationships-navigationsegenskaben for gruppeværdi for firmaobjektet. Forskellen er, at for den forrige forespørgsel, behøver du ikke at kende MetadataId for firmaobjektet.

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

Forespørge globale OptionSets

Du kan bruge GlobalOptionSetDefinitions-objektsætstien for at hente oplysninger om globale grupperede indstillinger, men denne sti understøtter ikke brugen af $filter-systemforespørgselsindstillingen. Så medmindre du kender MetadataId for en bestemt global grupperet indstilling, kan du kun hente dem alle. Du kan også få adgang til definitionen af en global grupperet indstilling inde fra GlobalOptionSet-navigationsegenskaben for enkeltværdi for alle attributter, der bruger den. Denne er tilgængelig for alle Entity types that inherit from activitypointer.Flere oplysninger:Hentning af attributter

Se også

Bruge Web API med Dynamics 365-metadata
Hente metadata efter navn eller MetadataId
Oprette og opdatere objektdefinitioner med Web API
Oprette og opdatere objektrelationer med Web API

Microsoft Dynamics 365

Del via

Forespørg på metadata ved hjælp af Web-API'en

Dette emne indeholder

Forespørgsel af objekttypen EntityMetadata

Bruge enum-typer i $filter-operationer

Bruge komplekse typer i $filter-operationer

Forespørger EntityMetadata-attributter

Filtrering efter krævet niveau

Hentning af attributter

Forespørge metadata for relation

Forespørge globale OptionSets

Se også

Yderligere ressourcer