Del via

Brug Web API-handlinger

  • Artikel

 

Udgivet: januar 2017

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

Handlinger og funktioner repræsenterer handlinger, der kan genbruges, og som du kan udføre ved hjælp af Web-API'en. Brug en POST-anmodning med handlinger, der er angivet i Web API Action Reference, til at udføre handlinger, der har bivirkninger. Du kan også definere brugerdefinerede handlinger, som derefter er tilgængelige, så du kan bruge dem.

Dette emne indeholder

Ubundne handlinger

Bundne handlinger

Brug en brugerdefineret handling

Angive objektparametertype

Ubundne handlinger

Handlinger defineres i d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Som et eksempel er følgende definitionen af den WinOpportunity Action, der er repræsenteret i CSDL.

<Action Name="WinOpportunity">
  <Parameter Name="OpportunityClose" Type="mscrm.opportunityclose" Nullable="false" />
  <Parameter Name="Status" Type="Edm.Int32" Nullable="false" />
</Action>

WinOpportunity-handlingen svarer til den WinOpportunityRequest, der bruger organisationstjenesten. Brug denne handling til at indstille tilstanden for en salgsmulighed til Vundet og oprette en opportunityclose EntityType for at registrere hændelsen. Denne handling indeholder ikke en returværdi. Hvis den lykkes, er handlingen fuldført.

OpportunityClose-parameteren kræver en JSON-repræsentation af det opportunityclose-objekt, der skal oprettes i handlingen. Dette objekt skal være relateret til den salgsmulighed, der udsteder opportunityid-navigationsegenskaben med en enkelt værdi. I JSON indstilles dette ved hjælp af @odata.bind-anmærkningen, som forklaret i Tilknyt objekter ved oprettelse.

Status-parameteren skal indstilles til statussen for opportunity, når den er lukket. Du kan finde standardværdien for denne i opportunity EntityType statuscode-egenskaben. Indstillingen Vundet har værdien 3. Du spørger måske dig selv, hvorfor det er nødvendigt at indstille denne værdi, når der er kun én statusårsagsindstilling, der repræsenterer Vundet? Årsagen er, at fordi du kan definere brugerdefinerede statusindstillinger, der repræsenterer en gevinst, f.eks. stor gevinst eller lille gevinst, kan værdien potentielt være forskellige fra 3 i den pågældende situation.

Følgende eksempel er HTTP-anmodning og -svar på opkald til WinOpportunity-handlingen for en salgsmulighed med en opportunityid-værdi på b3828ac8-917a-e511-80d2-00155d2a68d2.

  • Anmodning

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

{
 "Status": 3,
 "OpportunityClose": {
  "subject": "Won Opportunity",
  "opportunityid@odata.bind": "cc_WebAPI_ServiceURI/opportunities(b3828ac8-917a-e511-80d2-00155d2a68d2)"
 }
}

  • Svar

    HTTP/1.1 204 No Content
OData-Version: 4.0

Bundne handlinger

I d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl, når et Action-element repræsenterer en bundet handling, har det en IsBound-attribut med værdien true. Det første Parameter-element, der er defineret i handlingen, repræsenterer det objekt, som handlingen er bundet til. Når Type-attributten for parameteren er en samling, er handlingen bundet til en samling af objekter. Som et eksempel er følgende definitionen af den AddToQueue Action, der er repræsenteret i CSDL:

 <ComplexType Name="AddToQueueResponse">
 <Property Name="QueueItemId" Type="Edm.Guid" Nullable="false" />
 </ComplexType>
 <Action Name="AddToQueue" IsBound="true">
  <Parameter Name="entity" Type="mscrm.queue" Nullable="false" />
  <Parameter Name="Target" Type="mscrm.crmbaseentity" Nullable="false" />
  <Parameter Name="SourceQueue" Type="mscrm.queue" />
  <Parameter Name="QueueItemProperties" Type="mscrm.queueitem" />
  <ReturnType Type="mscrm.AddToQueueResponse" Nullable="false" />
</Action>

Den bundne handling svarer til den AddToQueueRequest, der bruges af organisationstjenesten. I Web API'en er denne handling bundet til den queue EntityType, der repræsenterer AddToQueueRequest.DestinationQueueId-egenskaben. Denne handling accepterer flere parametre yderligere og returnerer et AddToQueueResponse ComplexType, der svarer til den AddToQueueResponse, som organisationstjenesten returnerede. Når en handling returnerer en kompleks type, vises definitionen på den komplekse type direkte over handlingen i CSDL'et.

En bundet handling 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.

Når du aktiverer af en bundet funktion, skal du medtage det fulde navn på funktionen, herunder Microsoft.Dynamics.CRM-navneområdet. Hvis du ikke medtager det fulde navn, vises følgende fejlmeddelelse: Status Code:400 Request message has unresolved parameters.

Følgende eksempel viser, hvordan du føjer et bogstav til en kø ved hjælp af AddToQueue Action. Fordi Target-parametertypen ikke er specifik (mscrm.crmbaseentity), skal du eksplicit angive objekttypen ved hjælp af @odata.type-egenskabsværdien for det fulde navn på objektet, herunder Microsoft.Dynamics.CRM-navneområdet. I dette tilfælde Microsoft.Dynamics.CRM.letter.Flere oplysninger:Angive objektparametertype

  • Anmodning

    POST cc_WebAPI_ServiceURI/queues(56ae8258-4878-e511-80d4-00155d2a68d1)/Microsoft.Dynamics.CRM.AddToQueue HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "Target": {
  "activityid": "59ae8258-4878-e511-80d4-00155d2a68d1",
  "@odata.type": "Microsoft.Dynamics.CRM.letter"
 }
}

  • Svar

    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.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

Brug en brugerdefineret handling

Hvis du definerer brugerdefinerede handlinger for din organisation eller løsning, medtages de også i d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Oplysninger om oprettelse af handlinger ved hjælp af tilpasningsværktøjerne i programmet finder du i TechNet-emnet Handlinger. Du kan finde oplysninger om oprettelse og brug af dine egne brugerdefinerede handlinger under Oprette dine egne handlinger.

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.

Eksempel på brugerdefineret handling: Føje en note til en kontakt

Lad os sige, at du vil oprette en brugerdefineret handling, der føjer en ny note til en bestemt kontakt. Du kan oprette en brugerdefineret handling, der er bundet til kontaktobjektet, med følgende egenskaber.

UI Label

Værdi

Procesnavn

AddNoteToContact

Entydigt navn

new_AddNoteToContact

Objekt

Kontaktperson

Kategori

Handling

Procesargumenter

Navn

Type

Krævet

Retning

NoteTitle

Streng

Krævet

Input

NoteText

Streng

Krævet

Input

NoteReference

EntityReference

Krævet

Resultat

Trin

Navn

Trintype

Beskrivelse

Opret noten

Opret post

Titel = {NoteTitle(Arguments)}

Notetekst = {NoteText(Arguments)}

Angående = {Contact{Contact}}

Returner en reference til noten

Tildel værdi

NoteReference værdi = {Note(Opret noten (Bemærk))}

Når du har publiceret og aktiveret den brugerdefinerede handling og har hentet CSDL'et, kan du se denne nye handling defineret.

<Action Name="new_AddNoteToContact" IsBound="true">
  <Parameter Name="entity" Type="mscrm.contact" Nullable="false" />
  <Parameter Name="NoteTitle" Type="Edm.String" Nullable="false" Unicode="false" />
  <Parameter Name="NoteText" Type="Edm.String" Nullable="false" Unicode="false" />
  <ReturnType Type="mscrm.annotation" Nullable="false" />
</Action>

Følgende HTTP-anmodning og svar viser, hvordan du kalder den brugerdefinerede handling, og det svar, der returneres, hvis handlingen lykkes.

  • Anmodning

    POST cc_WebAPI_ServiceURI/contacts(94d8c461-a27a-e511-80d2-00155d2a68d2)/Microsoft.Dynamics.CRM.new_AddNoteToContact HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "NoteTitle": "New Note Title",
 "NoteText": "This is the text of the note"
}

  • Svar

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

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

Angive objektparametertype

Når en handling kræver et objekt som en parameter og objekttypen er tvetydig, skal du bruge @odata.type-egenskab til at angive objekttypen. Værdien af denne egenskab er det fuldt kvalificerede navn på det objekt, som følger dette mønster:
Microsoft.Dynamics.CRM.+<objektets logiske navn>.

Som vist i sektionen Bundne handlinger ovenfor, er Target-parameter til AddToQueue Action en aktivitet. Men da alle aktiviteter nedarver fra activitypointer EntityType, skal du medtage følgende egenskab i objektet JSON for at angive, at objekttypen er et brev: "@odata.type": "Microsoft.Dynamics.CRM.letter".

To andre eksempler er AddMembersTeam Action og RemoveMembersTeam Action, fordi Members-parameteren er en samling af systemuser EntityType, som arver den ownerid primære nøgle fra principal EntityType. Hvis du sender følgende JSON som repræsenterende en enkelt systemuser i samlingen, det er klart, at objektet er en systemuser og ikke en team EntityType, der også arver fra hoved-entitytype.

    {
     "Members": [{
      "@odata.type": "Microsoft.Dynamics.CRM.systemuser",
      "ownerid": "5dbf5efc-4507-e611-80de-5065f38a7b01"
     }] 
    }

Hvis du ikke angiver objekttypen i denne situation, kan du få følgende fejlmeddelelse: "EdmEntityObject passed should have the key property value set.".

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
Bruge Web-API-funktioner
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