Bruge Web-API-funktioner
Udgivet: januar 2017
Gælder for: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Funktioner og handlinger repræsenterer handlinger, der kan genbruges, og som du kan udføre ved hjælp af Web-API'en. Der findes to funktionstyper i Web-API'en:
Funktioner
Brug en GET-anmodning med funktioner, der er angivet i Web API Function Reference, til at udføre handlinger, der ikke har bivirkninger. Disse funktioner henter normalt data. De returnerer enten en samling eller en kompleks type. Hver af disse funktioner har en tilsvarende meddelelse i organisationstjenesten.Funktioner til forespørgsler
Brug de funktioner, der er angivet i Web API Query Function Reference til at vurdere egenskaberne og værdierne, når du sammensætter en forespørgsel. Hver af disse funktioner har en tilsvarende ConditionOperator-værdi.
Dette emne indeholder
Overførsel af parametre til en funktion
Videregiv reference til en enhed til en funktion
Bundne og ubundne funktioner
Oprette en forespørgsel med funktioner
Overførsel af parametre til en funktion
For disse funktioner, der kræver parametre, er det bedst at overføre værdier ved hjælp af parametre. Når du for eksempel bruger GetTimeZoneCodeByLocalizedName Function, skal du medtage LocalizedStandardName og LocaleId-parameterværdierne. Så kan du bruge følgende indbyggede syntaks, som vist her.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName='Pacific Standard Time',LocaleId=1033)
Men der er et åbent spørgsmål ved at bruge DateTimeOffset-værdier med indbygget syntaks, som beskrevet i følgende artikel: DateTimeOffset som forespørgselsparameter #204.
Derfor er den bedste fremgangsmåde at overføre værdierne som parametre som vist i følgende kodeeksempel. Hvis du bruger denne fremgangsmåde, kan du undgå det åbne problem, der gælder for DateTimeOffset.
GET cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific Standard Time'&@p2=1033
Parameteraliaser gør det også muligt at genbruge parameterværdier for at reducere den samlede længde af URL, når parameterværdien bruges flere gange.
Videregiv reference til en enhed til en funktion
Visse funktioner kræver, at en reference videregives til et eksisterende objekt. Følgende funktioner har f.eks. en parameter, der kræver en crmbaseentity EntityType:
Når du videregiver en reference til et eksisterende objekt, kan du bruge @odata.id-anmærkningeb til Uri for objektet. Hvis du f.eks. bruger RetrievePrincipalAccess Function, kan du bruge følgende Uri til angivelse af hentning af adgang til en bestemt kontakt:
GET cc_WebAPI_ServiceURI/systemusers(af9b3cf6-f654-4cd9-97a6-cf9526662797)/Microsoft.Dynamics.CRM.RetrievePrincipalAccess(Target=@tid)?@tid={'@odata.id':'contacts(9f3162f6-804a-e611-80d1-00155d4333fa)'}
@odata.id-anmærkningen kan være fuld Uri, men en relativ Uri fungerer også.
Bundne og ubundne funktioner
Kun de funktioner, der findes i Web API Function Reference, kan være bundet. Forespørgselsfunktioner er aldrig bundet.
Bundne funktioner
I d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl, når et Function-element repræsenterer en bundet funktion, har det en IsBound-attribut med værdien true. Det første Parameter-element, der er defineret i funktionen, repræsenterer det objekt, som funktionen er bundet til. Når Type-attributten for parameteren er en samling, er funktionen bundet til en samling af objekter. Som et eksempel er følgende definitionen af den CalculateTotalTimeIncident Function og CalculateTotalTimeIncidentResponse ComplexType i CSDL'et.
<ComplexType Name="CalculateTotalTimeIncidentResponse">
<Property Name="TotalTime" Type="Edm.Int64" Nullable="false" />
</ComplexType>
<Function Name="CalculateTotalTimeIncident" IsBound="true">
<Parameter Name="entity" Type="mscrm.incident" Nullable="false" />
<ReturnType Type="mscrm.CalculateTotalTimeIncidentResponse" Nullable="false" />
</Function>
Den bundne funktion svarer til den CalculateTotalTimeIncidentRequest, der bruges af organisationstjenesten. I Web API'en er denne funktion bundet til den incident EntityType, der repræsenterer CalculateTotalTimeIncidentRequest.IncidentId-egenskaben. I stedet for at returnere en CalculateTotalTimeIncidentResponse, returnerer denne funktion en CalculateTotalTimeIncidentResponse ComplexType. Når en funktion returnerer en kompleks type, vises definitionen på den direkte over definitionen på funktionen i CSDL'et.
Hvis du vil aktivere en bundet funktion, skal du føje det fulde navn på funktionen til URL og medtage alle navngivne parametre i parentes efter funktionsnavnet. Funktionens fulde navn indeholder navneområdet Microsoft.Dynamics.CRM. Funktioner, der ikke er bundet, må ikke bruge det fulde navn.
Vigtigt
En bundet funktion skal aktiveres ved hjælp af en URI for at angive den første værdi for parameteren. Du kan ikke angive den som en navngivet parameterværdi.
Følgende eksempel vises ved hjælp af CalculateTotalTimeIncident Function, som er bundet til hændelsesobjektet.
Anmodning
GET cc_WebAPI_ServiceURI/incidents(90427858-7a77-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Svar
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context":"cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse","TotalTime":30 }
Ubundne funktioner
WhoAmI Function er ikke bundet til et objekt. Den er defineret i CSDL'et uden IsBound-attribut.
<ComplexType Name="WhoAmIResponse">
<Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
<Property Name="UserId" Type="Edm.Guid" Nullable="false" />
<Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>
<Function Name="WhoAmI">
<ReturnType Type="mscrm.WhoAmIResponse" Nullable="false" />
</Function>
Denne funktion svarer til WhoAmIRequest og returnerer en WhoAmIResponse ComplexType, der svarer til den WhoAmIResponse, der bruges af organisationstjenesten. Denne funktion har ikke nogen parametre.
Under aktivering af en ubundet funktion, skal du kun bruge funktionsnavnet som vist i følgende eksempel.
Anmodning
GET cc_WebAPI_ServiceURI/WhoAmI() HTTP/1.1 Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0Svar
HTTP/1.1 200 OK Content-Type: application/json; odata.metadata=minimal OData-Version: 4.0 { "@odata.context": "cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse", "BusinessUnitId": "ded5a64f-f06d-e511-80d0-00155db07cb1", "UserId": "d96e9f55-f06d-e511-80d0-00155db07cb1", "OrganizationId": "4faf1f34-f06d-e511-80d0-00155db07cb1" }
Oprette en forespørgsel med funktioner
Der er to måder, funktioner kan bruges til at styre data, der returneres med forespørgsler. Visse funktioner giver mulighed for styring med de kolonner eller betingelser, som de returnerer, og du bruger forespørgselsfunktioner til at evaluere betingelserne i en forespørgsel.
Sammensættelige funktioner
Nogle funktioner, der er angivet i Web API Function Reference, returnerer en samling objekter. Et undersæt af disse funktioner er sammensættelige, hvilket betyder, at du kan medtage en ekstra $select eller $filter-systemforespørgselsindstilling for at styre, hvilke kolonner der skal returneres i resultaterne. Disse funktioner har en IsComposable-attribut i CSDL'et. Hver af disse funktioner er en medfølgende meddelelse i organisationstjenesten, der accepterer en parameter af typen ColumnSet eller QueryBase.OData-systemforespørgselsindstillingerne giver samme funktionalitet, så disse funktioner ikke har de samme parametre som deres følgemeddelelser i organisationstjenesten. I følgende tabel vises en liste over de sammensættelige funktioner i denne version.
Funktioner til forespørgsler
Funktioner, der er angivet i Web API Query Function Reference, bruges til oprettelse af en forespørgsel. Disse funktioner kan bruges på en måde, der svarer til de Standardforespørgselfunktioner, men der er nogle vigtige forskelle.
Du skal bruge det fulde navn på funktionen og medtage navnene på parametrene. Følgende eksempel viser, hvordan du bruger LastXHours Function til at returnere alle firmaobjekter, der er ændret inden for de sidste 12 timer.
GET cc_WebAPI_ServiceURI/accounts?$select=name,accountnumber&$filter=Microsoft.Dynamics.CRM.LastXHours(PropertyName=@p1,PropertyValue=@p2)&@p1='modifiedon'&@p2=12
Se også
Web API-funktioner og handlingseksempel (C#)
Eksempel på web-API-funktioner og handlinger (JavaScript på klientsiden)
Udføre operationer ved hjælp af web-API
Skrive HTTP-anmodninger og håndtere fejl
Forespørg på data ved hjælp af Web-API'en
Oprette et objekt ved hjælp af Web-API
Hente et objekt ved hjælp af web-API'et
Opdatere og slette objekter ved hjælp af web-API'et
Tilknytte og fjerne tilknytningen af objekter ved hjælp af web-API'et
Brug Web API-handlinger
Udføre batchhandlinger ved hjælp af Web-API
Efterligne en anden bruger ved hjælp af Web-API'en
Udfør betingede operationer ved hjælp af web-API
Microsoft Dynamics 365
© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret