Delen via

Web-API-acties gebruiken

  • Artikel

 

Gepubliceerd: januari 2017

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

Acties en functies staan voor herbruikbare bewerkingen die u kunt uitvoeren met de web-API. Gebruik een POST-aanvraag met acties die in Web API Action Reference worden vermeld, om bewerkingen uit te voeren die bijwerkingen hebben. U kunt ook aangepaste acties definiëren die u vervolgens kunt gebruiken.

In dit onderwerp

Ongebonden acties

Gebonden acties

Een aangepast actie gebruiken

Het type van de entiteitsparameter opgeven

Ongebonden acties

Acties worden gedefinieerd in d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Hierna volgt als voorbeeld de definitie van WinOpportunity Action die wordt weergegeven in de CSDL.

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

De actie WinOpportunity komt overeen met WinOpportunityRequest die de organisatieservice gebruikt. Gebruik deze actie om de status van een verkoopkans in te stellen op Binnengehaald en een opportunityclose EntityType te maken om de gebeurtenis vast te leggen. Deze actie omvat geen retourwaarde. Als deze geslaagd is, is de bewerking voltooid.

De parameter OpportunityClose vereist een JSON-weergave van de entiteit opportunityclose om de bewerking te maken. Deze entiteit moet zijn gerelateerd aan de verkoopkans waarvoor de single-valued navigatie-eigenschap opportunityid wordt uitgegeven. In de JSON wordt dit ingesteld met de annotatie @odata.bind, zoals uitgelegd in Entiteiten koppelen bij het maken.

De parameter Status moet worden ingesteld op de status voor de opportunity wanneer deze is afgesloten. U kunt de standaardwaarde hiervoor in de eigenschap opportunity EntityTypestatuscode vinden. De optie Binnengehaald heeft een waarde van 3. Mogelijk vraagt u zichzelf af waarom het nodig is om deze waarde in te stellen als er maar één optie voor de reden van status is die Binnengehaald vertegenwoordigt. De reden is dat u mogelijk aangepaste statusopties wilt definiëren om een binnengehaalde verkoopkans te vertegenwoordigen, zoals Grote binnengehaald of Kleine binnengehaald. De waarde kan dus anders zijn dan 3 in die situatie.

Het volgende voorbeeld is de HTTP-aanvraag en -respons om de actie WinOpportunity aan te roepen voor een verkoopkans met een opportunityid-waarde van b3828ac8-917a-e511-80d2-00155d2a68d2.

  • Aanvraag

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

  • Respons

    HTTP/1.1 204 No Content
OData-Version: 4.0

Gebonden acties

Wanneer in het d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl een element Action een gebonden actie vertegenwoordigt, heeft het een kenmerk IsBound met de waarde true. Het eerste element Parameter die in de actie is gedefinieerd, vertegenwoordigt de entiteit waaraan de bewerking is gebonden. Wanneer het kenmerk Type van de parameter een verzameling is, is de bewerking gebonden aan een verzameling van entiteiten. Hierna volgt bijvoorbeeld de definitie van AddToQueue Action die wordt weergegeven in de 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>

Deze gebonden actie is vergelijkbaar met de AddToQueueRequest die door de organisatieservice wordt gebruikt. In de web-API wordt deze actie gebonden aan de queue EntityType die de eigenschap AddToQueueRequest.DestinationQueueId vertegenwoordigt. Deze actie accepteert verschillende extra parameters en retourneert een AddToQueueResponse ComplexType die overeenkomt met de AddToQueueResponse die door de organisatieservice wordt geretourneerd. Wanneer een actie een complex type retourneert, wordt de definitie van het complexe type direct boven de actie in de CSDL weergegeven.

Een gebonden actie moet worden aangeroepen met een URI om de eerste parameterwaarde in te stellen. U kunt deze niet als een benoemde parameterwaarde instellen.

Wanneer een gebonden functie wordt aangeroepen, moet u de volledige naam van de functie opnemen, inclusief de naamruimte Microsoft.Dynamics.CRM. Als u niet de volledige naam opneemt, krijgt u het volgende foutbericht: Status Code:400 Request message has unresolved parameters.

In het volgende voorbeeld wordt met de AddToQueue Action een brief toegevoegd aan een wachtrij. Aangezien het type van het parametertype Target niet specifiek is (mscrm.crmbaseentity), moet u het type van het object expliciet declareren met de eigenschapswaarde @odata.type van de volledige naam van de entiteit, inclusief de naamruimte Microsoft.Dynamics.CRM. In dit geval: Microsoft.Dynamics.CRM.letter.Meer informatie:Het type van de entiteitsparameter opgeven

  • Aanvraag

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

  • Respons

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

Een aangepast actie gebruiken

Als u aangepaste acties voor uw organisatie of oplossing definieert, worden deze ook opgenomen in het d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl. Voor informatie over het maken van acties met de aanpassingshulpmiddelen in de toepassing raadpleegt u het TechNet-onderwerp Acties. Voor informatie over het maken en gebruiken van uw eigen aangepaste acties raadpleegt u Uw eigen acties maken.

Ongeacht of de bewerkingen in uw aangepaste actie bijwerkingen hebben, kunnen ze mogelijk gegevens wijzigen en worden daarom als acties in plaats van functies beschouwd. Er is geen manier om een aangepaste functie te maken.

Voorbeeld van aangepaste actie: Een notitie toevoegen aan een contactpersoon

Stel dat u een aangepaste actie wilt maken waarmee een nieuwe notitie wordt toegevoegd aan een bepaalde contactpersoon. U kunt een aangepaste actie maken die aan de entiteit Contactpersoon is gebonden met de volgende eigenschappen.

UI Label

waarde

Procesnaam

AddNoteToContact

Unieke naam

new_AddNoteToContact

Entiteit

Contactpersoon

Categorie

Actie

Procesargumenten

Naam

Type

Vereist

Richting

NoteTitle

Tekenreeks

Vereist

Invoer

NoteText

Tekenreeks

Vereist

Invoer

NoteReference

EntityReference

Vereist

Uitvoer

Stappen

Naam

Staptype

Beschrijving

De notitie maken

Record maken

Titel = {NoteTitle(Arguments)}

Notitietekst = {NoteText(Arguments)}

Betreft = {Contact{Contact}}

Een verwijzing naar de notitie retourneren

Waarde toewijzen

Waarde NoteReference = {Note(Create the note (Note))}

Deze nieuwe actie is gedefinieerd wanneer u de CSDL downloadt na het publiceren en activeren van de aangepaste actie.

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

De volgende HTTP-aanvraag en -respons toont hoe u de aangepaste actie kunt aanroepen en welke respons wordt geretourneerd als dit is gelukt.

  • Aanvraag

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

  • Respons

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

Het type van de entiteitsparameter opgeven

Wanneer een actie een entiteit vereist als parameter en het type entiteit dubbelzinnig is, moet u met de eigenschap @odata.type het type entiteit opgeven. De waarde van deze eigenschap is de volledig gekwalificeerde naam van de entiteit in de volgende notatie:
Microsoft.Dynamics.CRM.<>

Zoals weergegeven in de sectie Gebonden acties hierboven, is de parameter Target voor de AddToQueue Action een activiteit. Maar omdat alle activiteiten overnemen van activitypointer EntityType, moet u de volgende eigenschap opnemen in de entiteits-JSON om op te geven dat het entiteitstype een brief is: "@odata.type": "Microsoft.Dynamics.CRM.letter".

Twee andere voorbeelden zijn AddMembersTeam Action en RemoveMembersTeam Action, omdat de parameter Members een verzameling is van systemuser EntityType die de primaire sleutel ownerid overneemt van het principal EntityType. Als u de volgende JSON doorgeeft om één systemuser in de verzameling te vertegenwoordigen, is het duidelijk dat de entiteit een systemuser en niet een team EntityType, die eveneens overneemt van het hoofdentiteitstype.

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

Als u in deze situatie niet het entiteitstype opgeeft, kan het volgende foutbericht worden gegenereerd: "EdmEntityObject passed should have the key property value set.".

Zie ook

Web API-functies en actievoorbeeld (C#)
Voorbeeld web-API-functies en acties (JavaScript op client)
Bewerkingen uitvoeren met de web-API
HTTP-aanvragen opstellen en fouten afhandelen
Querygegevens met behulp van de web-API
Een entiteit maken met de web-API
Een entiteit ophalen met de web-API
Entiteiten bijwerken en verwijderen met de Web-API
Entiteiten koppelen en ontkoppelen met de web-API
Web-API-functies gebruiken
Batchbewerkingen uitvoeren met de Web API
Zich als een andere gebruiker voordoen die de Web API gebruikt
Voorwaardelijke bewerkingen uitvoer met de web-API

Microsoft Dynamics 365

© 2017 Microsoft. Alle rechten voorbehouden. Auteursrecht