Web API-Funktionen- und Aktionen-Beispiel

  • Artikel

 

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Diese Beispielgruppe veranschaulicht, wie ungebundene und gebundene Funktionen und Aktionen, einschließlich benutzerdefinierter Aktionen mithilfe dem Microsoft Dynamics 365 Web API angerufen werden. Dieses Beispiel wurde als ein separates Projekt für die folgenden Sprachen implementiert:

In diesem Thema werden die Struktur und der Inhalt der Beispiele für eine slt.pätere, sprachunabhängigen Ebene behandelt. Wiederholen Sie die verknüpften Beispielthemen oben, um sprachspezifische Implementierungen und verwandte Details zu erhalten und zu sehen, wie die in diesem Thema beschriebenen Methoden verwendet werde.

Demonstriert

Dieses Beispiel wird in die folgenden Hauptabschnitte unterteilt und enthält Web-API-Funktionen und -Aktionen, die in den entsprechenden Themenabschnitten detailliert behandelt werden.

Themenabschnitt

Zugeordnete Themen

Beispieldaten

Verwenden von ungebundenen Funktion ohne Parameter

Ungebundene Funktionen

WhoAmI Function

systemuser EntityType

Verwenden von ungebundenen Funktion mit Parametern

Ungebundene Funktionen

GetTimeZoneCodeByLocalizedName Function

Verwenden von gebundenen Funktion ohne Parameter

Gebundene Funktionen

CalculateTotalTimeIncident Function

Verwenden von ungebundenen Aktionen mit Parametern

Ungebundene Aktionen

WinOpportunity Action

opportunity EntityType

Verwenden von gebundenen Aktionen mit Parametern

Gebundene Aktionen

AddToQueue Action

WhoAmI Function

systemuser EntityType

letter EntityType

Verwenden von gebundenen benutzerdefinierten Aktionen mit Parametern

Nutzen einer benutzerdefinierten Aktion

Gebundene Aktionen

contact EntityType

Verwenden von ungebundenen benutzerdefinierten Aktionen mit Parametern

Nutzen einer benutzerdefinierten Aktion

Ungebundene Aktionen

account EntityType

Behandlung von Ausnahmen für benutzerdefinierte Aktionen

Nutzen einer benutzerdefinierten Aktion

Ungebundene Aktionen

contact EntityType

Die folgenden Abschnitte enthalten eine kurze Diskussion zu den ausgeführten Dynamics 365 Web-API-Vorgängen, sowie den entsprechenden HTTP-Nachrichten und den Ausgaben, die der Konsolen zugeordnet sind.

Beispieldaten

Um die ordnungsgemäße Ausführung der Vorgänge in diesem Beispiel, erstellen Sie zuerst Beispieldaten auf dem Dynamics 365-Server. Diese Beispieldaten werden vom Server gelöscht, es sei denn, der Benutzer entscheidet sich, sie nicht zu löschen. Die Daten in diesem Beispiel werden wie folgt einzeln erstellt.

  • Erstellen Sie ein Konto (z. B.: Fourth Coffee) und ordnen Sie es einem Vorfall zu, der drei 30-minütige Aufgaben hat (insg. 90 Minuten). Nachdem die Aufgaben erstellt sind, werden sie als abgeschlossen markiert. Der Vorgang berechnet die gesamte Zeit, die zur Ausführung dieser drei Aufgaben erforderlich ist.

    {
  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
   }
  ]
 };

  • Erstellen Sie ein Konto und ordnen Sie es einer Verkaufschance zu. Diese Verkaufschance wird im Beispielvorgang als gewonnen markiert.

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

  • Erstellen Sie eine Brief-Aktivität. Der Brief wird im Beispielvorgang in die aktuelle Warteschlange des Benutzers hinzugefügt.

    {
  description: "Example letter"
}

  • Erstellen Sie einen Kontakt, der mit einer benutzerdefinierte Aktionen sample_AddNoteToContact im Beispielvorgang verwendet wird.

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

Beispielvorgänge

Die Beispielvorgänge in diesem Thema werden folgendermaßen organisiert.

  • Verwenden von Funktionen: Diese Vorgänge zeigen gebundene und ungebundene Funktionen, die Parameter akzeptieren oder nicht.

  • Verwenden von Aktionen: Diese Vorgänge zeigen gebundene und ungebundene Aktionen, die Parameter akzeptieren oder nicht.

  • Benutzerdefinierte Aktionen: Diese Vorgänge zeigen gebundene und ungebundene Aktionen und die Verarbeitung von benutzerdefinierte Fehlerausnahmen.

Verwenden von Funktionen

Funktionen sind Vorgänge, die keine Nebenwirkungen haben. Eine Funktion kann an eine Entitätsinstanz oder eine Entitätssammlung gebunden werden. Abfragefunktionen sind niemals gebunden. Weitere Informationen finden Sie unter Nutzen von Web-API-Funktionen. Dieser Abschnitt enthält Beispiele zur Verwendung von gebundenen und ungebundenen Funktionen und zur Übergabe von Parametern.

Verwenden von ungebundenen Funktion ohne Parameter

Verwenden Sie eine ungebundene Feature, um den aktuellen vollständigen Namen des Benutzers aus, wenn Sie das WhoAmI Function ausnutzen. Dieser Vorgang veranschaulicht, wie Sie eine ungebundene Funktion aufrufen, die keine Parameter annimmt. Dieser Vorgang gibt den vollständigen Namen des aktuellen Benutzers zurück.

Abrufen des Anforderung und Antwort für die WhoAmI Function.

HTTP-Anforderung

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

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

Verwenden von ungebundenen Funktion mit Parametern

Verwenden Sie eine ungebundene Funktion, um den Zeitzonencode abzurufen. Dieser Vorgang veranschaulicht, wie Sie eine ungebundene Funktion aufrufen, die Parameter annimmt. Dieser Vorgang gibt den Zeitzonencode für die angegebene Zeitzone zurück.Weitere Informationen:Übergeben von Parametern an eine Funktion

HTTP-Anforderung

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

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
}

Konsolenausgabe

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

Verwenden von gebundenen Funktion ohne Parameter

Verwenden Sie eine gebundene Funktion, um die vollständige Zeit zu erhalten, die für alle Aufgaben eines Vorfalls erforderlich war. Dieser Vorgang veranschaulicht, wie Sie eine gebundene Funktion aufrufen, die keine Parameter annimmt. Dieser Vorgang wird die Gesamtanzahl von Minuten zurück, die der Vorfall für alle zugehörigen Aufgaben erforderte. Die Funktion verwendet außerdem die Vorfalldaten, die Sie für das Beispielprogramm erstellen haben.Weitere Informationen:Gebundene Funktionen

HTTP-Anforderung

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

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
}

Konsolenausgabe

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

Verwenden von Aktionen

Aktionen sind Vorgänge, die Nebenwirkungen zulassen. Ein Aktion ist entweder gebunden oder ungebunden. Weitere Informationen finden Sie unter Nutzen von Web-API-Aktionen. Dieser Abschnitt enthält Beispiele zur Verwendung von gebundenen und ungebundenen Aktionen und zur Übergabe von Parametern. Er zeigt außerdem, wie benutzerdefinierte Aktionen verwenden werden und wie Ausnahmen dieser benutzerdefinierten Aktionen behandelt werden.

Verwenden von ungebundenen Aktionen mit Parametern

Verwenden Sie eine ungebundene Aktion, die einen Satz Parameter verarbeitet. Dieser Vorgang umfasst eine Verkaufschance und markiert sie über den Aufruf von WinOpportunity Action als gewonnen. Der opportunity EntityType wurde als Beispieldaten vorher im Programm erstellt.Weitere Informationen:Ungebundene Aktionen

HTTP-Anforderung

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

HTTP/1.1 204 No Content
OData-Version: 4.0

Konsolenausgabe

Unbound Action: WinOpportunity
    Opportunity won.

Verwenden von gebundenen Aktionen mit Parametern

Verwenden Sie eine gebundene Aktion, die einen Satz Parameter verarbeitet. Dieser Vorgang fügt einen Brief zur Warteschlange des aktuellen Benutzers hinzu. Um dies zu erzielen, verwenden wir die WhoAmI Function und systemuser EntityType, um einen Verweis auf die aktuellen Warteschlange des Benutzers zu erhalten. Wir benötigen auch Verweis auf den letter EntityType. Der Brief wurde als Beispieldaten vorher im Programm erstellt. Anschließend wird die gebundene AddToQueue Action aufgerufen, um den Brief der Warteschlange des aktuellen Benutzers hinzuzufügen.Weitere Informationen:Gebundene Aktionen

HTTP-Anforderung

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

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

Konsolenausgabe

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

Verwenden von benutzerdefinierten Aktionen

Wenn Sie benutzerdefinierte Aktionen in Ihrer Lösung definieren, können Sie diese über die Dynamics 365-Web-API aufrufen. Unabhängig davon, ob die Vorgänge in der benutzerdefinierten Aktion Nebenwirkungen haben, können sie möglicherweise Daten ändern und gelten daher eher als Aktionen und nicht als Funktionen. Es gibt keine Möglichkeit, eine benutzerdefinierte Funktion zu erstellen.Weitere Informationen:Nutzen einer benutzerdefinierten Aktion.

Dieses Beispiel verfügt über zwei benutzerdefinierte Aktionen. Sie erfordern beide Parameter. Eine ist gebunden und die andere ungebunden.

  • sample_AddNoteToContact: Eine gebundene benutzerdefinierte Aktion, die zwei Parameter verarbeitet. Einer ist ein NoteTitle und der andere ist ein NoteText. Diese benutzerdefinierte Aktion für einem contact EntityType eine Notiz hinzu. Unten finden Sie ein Screenshot der Informationen-Seite dieser benutzerdefinierten Aktion.

    Custom Action - AddNoteToContact information

  • sample_CreateCustomer: Eine ungebundene benutzerdefinierte Aktion, die verschiedene Parameter erfordert (je nach Typ des zu erstellenden Kunden). Wenn beispielsweise AccountType "Firma" ist, dann ist nur der AccountName-Parameter erforderlich. Wenn AccountType "Kontakt" ist, sind die Parameter ContactFirstName und ContactLastName erforderlich. Unten finden Sie ein Screenshot der Informationen-Seite dieser benutzerdefinierten Aktion.

    Custom Action - CreateCustomer information

Verwenden von gebundenen benutzerdefinierten Aktionen mit Parametern

Dieses Beispiel ruft die benutzerdefinierte Aktion sample_AddNoteToContact auf, die an Kontaktentität mit den benötigten Parametern gebunden ist. Diese benutzerdefinierte Aktion für eine Notiz zu einem vorhanden Kontakt hinzu. Diese Aktion gibt eine Entität mit einer annotationid-Eigenschaft zurück. Um das Hinzufügen der Notiz anzuzeigen, wird die annotationid verwendet, um Informationen zur Notiz anzufordern.

Die Anfrage und Antwort der Aktion.

HTTP-Anforderung

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

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

Die Anfrage und Antwort der Notiz (Annotation).

HTTP-Anforderung

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

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

Konsolenausgabe

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.

Verwenden von ungebundenen benutzerdefinierten Aktionen mit Parametern

Dieser Vorgang ruft die benutzerdefinierte Aktion sample_CreateCustomer auf, um einen "Konto"-Kunden zu erstellen. Die erforderliche Parameter sind CustomerType mit dem Wert account.

HTTP-Anforderung

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

HTTP/1.1 204 No Content
OData-Version: 4.0

Behandlung von Ausnahmen für benutzerdefinierte Aktionen

Dieses Beispiel wird angezeigt, das benutzerdefinierte Aktionen benutzerdefinierten Fehlermeldungen zurückgeben können. Sie verarbeiten benutzerdefinierte Ausnahmen genauso wie Standardausnahmen. Um die benutzerdefinierte Fehlermeldung aus der angepassten Aktion sample_CreateCustomer zu erhalten, erstellt dieses Beispiel einen "Kontakt"-Kunden. Allerdings übergeben wir absichtlich die falsche Parameter für den CustomerType-Parameter. Dieser Vorgang fängt dann die Ausnahme ab und zeigt die Fehlermeldung an. Dann führt das Beispielprogramm fort.

HTTP-Anforderung

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

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

Konsolenausgabe

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

Siehe auch

Verwenden der Microsoft Dynamics 365-Web-API
Nutzen von Web-API-Funktionen
Nutzen von Web-API-Aktionen
Internet-API-Funktionen- und Aktionen-Beispiel (C#)
Beispiele von Web API-Funktionen und Aktionen (clientseitiges JavaScript)

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright