Del via

Web API-funktioner og handlingseksempel

  • Artikel

 

Udgivet: januar 2017

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

Denne gruppe af eksempler demonstrerer, hvordan du udfører bundne og ubundne funktioner og handlinger, herunder brugerdefinerede handlinger, ved hjælp af Microsoft Dynamics 365-Web-API'en. Dette eksempel er implementeret som et separat projekt på følgende sprog:

Dette emne beskriver strukturen og indholdet af eksemplet på et højere, sprogneutralt niveau. Gennemse de tilknyttede eksempelemner ovenfor for sprogspecifikke implementeringsoplysninger om, hvordan du udfører de handlinger, der er beskrevet i dette emne.

Demonstrerer

Dette eksempel er inddelt i følgende overordnede sektioner, som indeholder Web API-funktioner og -handlinger, der er beskrevet nærmere i de tilknyttede emnebegreber.

Emneafsnit

Tilknyttede emne(r)

Eksempeldata

Brug af ubundet funktion uden parametre

Ubundne funktioner

WhoAmI Function

systemuser EntityType

Brug af ubundet funktion med parametre

Ubundne funktioner

GetTimeZoneCodeByLocalizedName Function

Brug af bundet funktion uden parametre

Bundne funktioner

CalculateTotalTimeIncident Function

Brug af ubundet handling med parametre

Ubundne handlinger

WinOpportunity Action

opportunity EntityType

Brug af bundet handling med parametre

Bundne handlinger

AddToQueue Action

WhoAmI Function

systemuser EntityType

letter EntityType

Brug af bundet, brugerdefineret handling med parametre

Brug en brugerdefineret handling

Bundne handlinger

contact EntityType

Brug af ubundet, brugerdefineret handling med parametre

Brug en brugerdefineret handling

Ubundne handlinger

account EntityType

Håndtering af undtagelser for brugerdefinerede handlinger

Brug en brugerdefineret handling

Ubundne handlinger

contact EntityType

Følgende afsnit indeholder en kort beskrivelse af de Dynamics 365 Web API-handlinger, der udføres sammen med de tilsvarende HTTP-meddelelser og tilknyttede konsoloutput.

Eksempeldata

For at sikre, at handlingerne i dette eksempel fungerer korrekt, skal vi først oprette eksempeldata på Dynamics 365-serveren. Disse eksempeldata vil blive slettet fra serveren, medmindre brugeren vælger ikke at slette dem. Dataene i dette eksempel oprettes enkeltvist på følgende måde.

  • Opret en konto (f.eks. Fourth Coffee), og knyt den til en hændelse, der har tre opgaver á 30 minutter (90 minutter i alt). Når opgaverne er oprettet, bliver de markeret som fuldført. Handlingen vil beregne den samlede tid, det tog for at fuldføre disse tre opgaver.

    {
  title: "Sample Case",
  "customerid_account@odata.bind": accountUri,
  Incident_Tasks: [
   {
    subject: "Task 1",
    actualdurationminutes: 30
   },
   {
    subject: "Task 2",
    actualdurationminutes: 30
   },
   {
    subject: "Task 3",
    actualdurationminutes: 30
   }
  ]
 };

  • Opret en konto, og knyt den til en salgsmulighed Denne salgsmulighed vil blive markeret som vundet i eksempelhandlingen.

    {
 name: "Sample Account for WebAPIFunctionsAndActions sample",
 opportunity_customer_accounts: [{
  name: "Opportunity to win"
 }]
};

  • Opret en brevaktivitet Brevet vil blive føjet til den aktuelle brugers kø i eksempelhandlingen.

    {
  description: "Example letter"
}

  • Opret en kontakt, der skal bruges sammen med en brugerdefineret handling sample_AddNoteToContact i eksempelhandlingen.

    {
  firstname: "Jon",
  lastname: "Fogg"
}

Eksempelhandlinger

Eksempelhandlingerne i dette emne er arrangeret på følgende måder.

  • Arbejde med funktioner: Disse handlinger viser bundne og ubundne funktioner, der enten accepterer eller afviser parametre.

  • Arbejde med handlinger: Disse handlinger viser bundne og ubundne handlinger, der enten accepterer eller afviser parametre.

  • Brugerdefinerede handlinger: Disse handlinger vise bundne og ubundne handlinger, og hvordan du håndterer brugerdefinerede fejlundtagelser.

Arbejde med funktioner

Funktioner er handlinger, der ikke har nogen bivirkninger. En funktion kan være bundet til en objektforekomst eller en objektsamling. Forespørgselsfunktioner er aldrig bundet. Du kan finde flere oplysninger under Bruge Web-API-funktioner. Dette afsnit vises eksempler på, hvordan bundne og ubundne funktioner bruges, og hvordan parametre overføres.

Brug af ubundet funktion uden parametre

Brug en ubundet funktion til at hente den aktuelle brugers fulde navn ved at benytte WhoAmI Function. Denne handling viser, hvordan du kalder en ubundet funktion, der ikke accepterer parametre. Denne handling returnerer den aktuelle brugers fulde navn.

Hentning af anmodningen og svar til WhoAmI Function.

HTTP-anmodning

GET http://cc_WebAPI_ServiceURI/WhoAmI HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP-svar

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 273

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.WhoAmIResponse",
   "BusinessUnitId":"0d6cc84a-d3f6-e511-80d0-00155da84802",
   "UserId":"b08dc84a-d3f6-e511-80d0-00155da84802",
   "OrganizationId":"0f47eae2-a906-4ae4-9215-f09875979f6a"
}

Brug af ubundet funktion med parametre

Brug en ubundet funktion til at hente tidszonekoden. Denne handling viser, hvordan du kalder en ubundet funktion, der accepterer parametre. Denne handling returnerer den aktuelle tidszonekode for den angivne tidszone.Flere oplysninger:Overførsel af parametre til en funktion

HTTP-anmodning

GET http://cc_WebAPI_ServiceURI/GetTimeZoneCodeByLocalizedName(LocalizedStandardName=@p1,LocaleId=@p2)?@p1='Pacific%20Standard%20Time'&@p2=1033 HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP-svar

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 154

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.GetTimeZoneCodeByLocalizedNameResponse",
   "TimeZoneCode":4
}

Konsoloutput

Unbound function: GetTimeZoneCodeByLocalizedName
    Function returned time zone Pacific Standard Time, with code '4'.

Brug af bundet funktion uden parametre

Brug en bundet funktion til at hente den samlede tid, det tog at fuldføre alle opgaver i en hændelse. Denne handling viser, hvordan du kalder en bundet funktion, der ikke accepterer parametre. Denne funktion returnerer de samlede antal minutter, hændelsen tog for at lukke alle opgaver. Denne funktion benytter også de hændelsesdata, vi har oprettet til dette eksempelprogram.Flere oplysninger:Bundne funktioner

HTTP-anmodning

GET http://cc_WebAPI_ServiceURI/incidents(3d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.CalculateTotalTimeIncident() HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP-svar

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 148

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.CalculateTotalTimeIncidentResponse",
   "TotalTime":90
}

Konsoloutput

Bound function: CalculateTotalTimeIncident
    Function returned 90 minutes - total duration of tasks associated with the incident.

Arbejde med handlinger

Handlinger er handlinger, der ikke tillader bivirkninger. En handling er bundet eller ubundet. Du kan finde flere oplysninger under Brug Web API-handlinger. Dette afsnit vises eksempler på, hvordan bundne og ubundne handlinger bruges, og hvordan parametre overføres. Det viser også, hvordan brugerdefinerede handlinger bruges, og hvordan undtagelser håndteres fra disse brugerdefinerede handlinger.

Brug af ubundet handling med parametre

Brug en ubundet handling, der benytter en række parametre. Denne handling lukker en salgsmulighed og markerer den som vundet ved at kalde WinOpportunity Action.opportunity EntityType blev oprettet som eksempeldata tidligere i programmet.Flere oplysninger:Ubundne handlinger

HTTP-anmodning

POST http://cc_WebAPI_ServiceURI/WinOpportunity HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

{
   "Status":3,
   "OpportunityClose":{
      "subject":"Won Opportunity",
      "opportunityid@odata.bind":"http://cc_WebAPI_ServiceURI/opportunities(47920da5-fb4a-e611-80d5-00155da84802)"
   }
}

HTTP-svar

HTTP/1.1 204 No Content
OData-Version: 4.0

Konsoloutput

Unbound Action: WinOpportunity
    Opportunity won.

Brug af bundet handling med parametre

Brug en bundet handling, der benytter en række parametre. Denne handling tilføjer et brev til den aktuelle brugers kø. For at opnå dette bruger vi WhoAmI Function og systemuser EntityType til at hente en reference til den aktuelle brugers kø. Vi har også brug for en reference til letter EntityType. Dette brev blev oprettet som eksempeldata tidligere i programmet. Derefter kaldes den bundne AddToQueue Action for at tilføje brevet til den aktuelle brugers kø.Flere oplysninger:Bundne handlinger

HTTP-anmodning

POST http://cc_WebAPI_ServiceURI/queues(1f7bcc50-d3f6-e511-80d0-00155da84802)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 110

{
   "Target":{
      "activityid":"4c920da5-fb4a-e611-80d5-00155da84802",
      "@odata.type":"Microsoft.Dynamics.CRM.letter"
   }
}

HTTP-svar

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 170

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
   "QueueItemId":"67bdfabd-fc4a-e611-80d5-00155da84802"
}

Konsoloutput

Bound Action: AddToQueue
    QueueItemId returned from AddToQueue Action: 67bdfabd-fc4a-e611-80d5-00155da84802

Arbejde med brugerdefinerede handlinger

Hvis du definerer brugerdefinerede handlinger for løsningen, du kan kalde dem ved hjælp af Dynamics 365 Web API'en. Uanset om de handlinger, der er inkluderet i din brugerdefinerede handling, har bivirkninger eller ej, kan de potentielt ændre data, og derfor anses de for handlinger frem for funktioner. Det er ikke muligt at oprette en brugerdefineret funktion.Flere oplysninger:Brug en brugerdefineret handling.

Med dette eksempel følger to brugerdefinerede handlinger. Begge kræver parametre, men én er bundet, og den anden er ubundet.

  • sample_AddNoteToContact En bundet, brugerdefineret handling, der benytter to parametre. En er NoteTitle, og den anden er NoteText. Den brugerdefinerede handling føjer en note til contact EntityType. Nedenfor vises et skærmbillede af siden Oplysninger for den brugerdefinerede handling.

    Custom Action - AddNoteToContact information

  • sample_CreateCustomer: En ubundet, brugerdefineret handling, der kræver forskellige parametre, afhængigt af hvilken type kunde der oprettes. Når AccountType f.eks. er "account", kræver den kun parameteren AccountName. Når AccountType er "contact", kræves parametrene ContactFirstName og ContactLastName. Nedenfor vises et skærmbillede af siden Oplysninger for den brugerdefinerede handling.

    Custom Action - CreateCustomer information

Brug af bundet, brugerdefineret handling med parametre

I dette eksempel kaldes den brugerdefinerede handling sample_AddNoteToContact, som er bundet til kontaktobjektet med de krævede parametre. Den brugerdefinerede handling føjer en note til en eksisterende kontakt. Denne handling returnerer et objekt med egenskaben annotationid. Hvis du vil vise, at noten er blevet tilføjet, bruges annotationid til at anmode om oplysninger om noten.

Anmodningen og svaret i handlingen.

HTTP-anmodning

POST http://cc_WebAPI_ServiceURI/contacts(4d920da5-fb4a-e611-80d5-00155da84802)/Microsoft.Dynamics.CRM.sample_AddNoteToContact HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 80

{
   "NoteTitle":"The Title of the Note",
   "NoteText":"The text content of the note."
}

HTTP-svar

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 149

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
   "annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802"
}

Anmodningen om og svaret for anmærkningen.

HTTP-anmodning

GET http://cc_WebAPI_ServiceURI/annotations(ba146d0b-fd4a-e611-80d5-00155da84802)?$select=subject,notetext&$expand=objectid_contact($select=fullname) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8

HTTP-svar

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Length: 450

{
   "@odata.context":"http://cc_WebAPI_ServiceURI/$metadata#annotations(subject,notetext,objectid_contact,objectid_contact(fullname))/$entity",
   "@odata.etag":"W/\"622978\"",
   "subject":"The Title of the Note",
   "notetext":"The text content of the note.",
   "annotationid":"ba146d0b-fd4a-e611-80d5-00155da84802",
   "objectid_contact":{
      "@odata.etag":"W/\"622968\"",
      "fullname":"Jon Fogg",
      "contactid":"4d920da5-fb4a-e611-80d5-00155da84802"
   }
}

Konsoloutput

Custom action: sample_AddNoteToContact
    A note with the title 'The Title of the Note' and the content 'The text content of the note.' was created and associated with the contact Jon Fogg.

Brug af ubundet, brugerdefineret handling med parametre

Denne handling kalder den brugerdefinerede handling sample_CreateCustomer for at oprette en "account"-kunde. Obligatoriske parametre overføres for en CustomerType for account.

HTTP-anmodning

POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103

{
   "CustomerType":"account",
   "AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}

HTTP-svar

HTTP/1.1 204 No Content
OData-Version: 4.0

Håndtering af undtagelser for brugerdefinerede handlinger

Dette eksempel viser, at brugerdefinerede handlinger kan returnere brugerdefinerede fejlmeddelelser. Brugerdefinerede undtagelser håndteres på samme måde, som du håndterer standardundtagelser. Hvis du vil hente den brugerdefinerede fejlmeddelelse fra den brugerdefinerede handling sample_CreateCustomer , oprette dette eksempel en "contact"-kunde. Men vi overfører bevidst de forkerte parametre for denne CustomerType-parameter. Denne handling registrerer undtagelsen, viser fejlmeddelelsen, og fortsætter derefter med eksempelprogrammet.

HTTP-anmodning

POST http://cc_WebAPI_ServiceURI/sample_CreateCustomer HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Content-Type: application/json; charset=utf-8
Content-Length: 103

{
   "CustomerType":"contact",
   "AccountName":"Account Customer Created in WebAPIFunctionsAndActions sample"
}

HTTP-svar

HTTP/1.1 500 Internal Server Error
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0
Content-Length: 2760

{
   "error":{
      "code":"",
      "message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
      "innererror":{
         "message":"ContactFirstName and ContactLastName are required when CustomerType is contact.",
         ...[truncated]
      }
   }
}

Konsoloutput

Expected custom error: ContactFirstName and ContactLastName are required when CustomerType is contact.

Se også

Brug Microsoft Dynamics 365 Web API
Bruge Web-API-funktioner
Brug Web API-handlinger
Web API-funktioner og handlingseksempel (C#)
Eksempel på web-API-funktioner og handlinger (JavaScript på klientsiden)

Microsoft Dynamics 365

© 2017 Microsoft. Alle rettigheder forbeholdes. Ophavsret