Nutzen von Web-API-Aktionen

Veröffentlicht: Januar 2017

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

Aktionen und Funktionen stellen wiederverwendbare Vorgänge dar, die Sie mithilfe derb Web-API ausführen können. Nutzen Sie eine POST-Anforderung mit den Aktionen, die in Web API Action Reference aufgeführt sind, um Vorgänge ausführen, die keine Nebenwirkungen haben. Sie können benutzerdefinierte Aktionen definieren, die für Ihre Verwendung bereitstehen.

In diesem Thema

Ungebundene Aktionen

Gebundene Aktionen

Nutzen einer benutzerdefinierten Aktion

Geben Sie Entitätsparametertyp an

Ungebundene Aktionen

Aktionen werden in d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl definiert. Als Beispiel wird die folgende Definition der WinOpportunity Action in der CSDL dargestellt.

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

Die WinOpportunity Aktion entspricht dem WinOpportunityRequest wenn das Organisationsservice verwendet wird. Verwenden Sie diese Aktion, um den Status einer Verkaufschance auf "Gewonnen" festzulegen und einen opportunityclose EntityType-Datensatz zur Aufzeichnung des Ereignisses zu erstellen. Diese Aktion umfasst keinen Rückgabewert. Wenn der Vorgang erfolgreich ausgeführt wird, ist er abgeschlossen.

Der OpportunityClose Parameter wird eine JSON Entität, in der Darstellung opportunityclose Entität, um den Vorgang zu erstellen. Diese Entität muss mit der Verkaufschance verbunden sein, die die opportunityid einzelbewertete Navigationseigenschaft ausstellt. In JSON wird dies mithilfe der @odata.bind-Anmerkung festgelegt, siehe Entitäten bei Erstellung zuordnen.

Der Parameter Status müssen auf den Status für opportunity gesetzt werden, wenn er geschlossen ist. Sie finden den Standardwert dafür in der opportunity EntityTypestatuscode-Eigenschaft. Die Option Gewonnen hat einen Wert von 3. Sie fragen sich möglicherweise, warum der Wert festgelegt werden muss, wenn es nur eine Statusgrund-Option gibt, die Gewonnen darstellt. Der Grund dafür ist, dass Sie möglicherweise benutzerdefinierte Statusoptionen definieren, um einen Gewinn darzustellen, beispielsweise einen großen oder kleinen Gewinn, sodass sich der Wert in dieser Situation möglicherweise von drei unterscheidet.

Das folgende Beispiel ist die HTTP-Anforderung und -Antwort zum Aufruf der WinOpportunity-Aktion für eine Verkaufschance mit einem opportunityid-Wert von b3828ac8-917a-e511-80d2-00155d2a68d2.

• Anforderung

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

• Antwort

  HTTP/1.1 204 No Content
  OData-Version: 4.0
  

Gebundene Aktionen

Im d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl, wenn ein Action-Element eine gebundene Aktion darstellt, besitzt es ein IsBound-Attribut mit dem Wert true. Das erste definierte Parameter-Element innerhalb der Aktion repräsentiert die Entität, an die die Operation geknüpft ist. Wenn das Attribut Type des Parameters eine Sammlung ist, wird der Vorgang an eine Entitätssammlung gebunden. Als Beispiel wird die folgende Definition der AddToQueue Action in der CSDL dargestellt:

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

Diese Bindungsaktion ähnelt AddToQueueRequest, was vom Organisationsservice verwendet wird. In der Web-API ist diese Aktion an queue EntityType gebunden, der die AddToQueueRequest.DestinationQueueId-Eigenschaft darstellt. Diese Aktion akzeptiert mehrere zusätzliche Parameter und gibt dann eine AddToQueueResponse ComplexType entsprechend der AddToQueueResponse vom Organisationsservice zurück. Wenn eine Aktion einen komplexen Datentyp zurückgibt, so wird dessen Definition direkt über der Definition der Aktion in CSDL angezeigt.

Eine Aktion muss mithilfe einer URI aufgerufen werden, um den ersten Parameterwert festzulegen. Sie können es nicht als Parameterwert mit Namen festlegen.

Beim Aufruf einer gebundenen Funktion müssen Sie den vollständigen Namen der Funktion einschließlich den Microsoft.Dynamics.CRM-Namespace angeben. Wenn Sie nicht den vollständigen Namen einschließen, wird die folgende Fehlermeldung angezeigt: Status Code:400 Request message has unresolved parameters.

Im folgenden Beispiel wird das Hinzufügen eines Schreibens zu einer Warteschlange mittels AddToQueue Action gezeigt. Da der Typ des Target-Parametertyps nicht spezifisch ist,(mscrm.crmbaseentity), müssen Sie explizit den typ des Objekts deklarierten, indem Sie den @odata.type-Eigenschaftswert des vollständigen Namens der Entität verwenden, einschließlich des Microsoft.Dynamics.CRM-Namespace. In diesem Fall: Microsoft.Dynamics.CRM.letter.Weitere Informationen:Geben Sie Entitätsparametertyp an

• Anforderung

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

• Antwort

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

Nutzen einer benutzerdefinierten Aktion

Wenn Sie benutzerdefinierte Aktionen für Ihre Organisation oder Lösung definieren, sind diese auch im d80cfb87-d4f1-4c75-bcc8-4f54d1351e26#bkmk_csdl enthalten. Informationen zum Erstellen von Aktionen mithilfe der Anpassungstools in der Anwendung finden Sie im TechNet-Thema Aktionen. Informationen zum Erstellen und Verwenden eigener benutzerdefinierter Aktionen finden Sie unter Erstellen Ihrer eigenen Aktionen.

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.

Benutzerdefiniertes Aktionsbeispiel: Hinzufügen einer Notiz zu einem Kontakt

Nehmen wir an, dass Sie eine benutzerdefinierte Aktion erstellen möchten, mit der eine neue Notiz zu einem bestimmten Kontakt hinzugefügt wird. Sie können eine benutzerdefinierte Aktionsgrenze zur Kontaktentität mit den folgenden Eigenschaften erstellen.

Argumente verarbeiten

Schritte

Nachdem Sie die angepasste Aktion veröffentlicht und aktiviert haben, finden Sie, wenn Sie das CSDL herunterladen, diese neue Aktion definiert.

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

Die folgende HTTP-Anforderung und -Antwort zeigt, wie die benutzerdefinierte Aktion und Antwort, die bei Erfolg zurückgegeben wird, aufgerufen werden.

• Anforderung

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

• Antwort

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

Geben Sie Entitätsparametertyp an

Wenn bei einer Aktion eine Entität erforderlich ist, weil ein Parameter und die Verwendungsart der Entität mehrdeutig ist, müssen Sie die @odata.type-Eigenschaft verwenden, um den Typ der Entität anzugeben. Der Wert dieser Eigenschaft ist der vollqualifizierte Name der Entität, der dem Muster folgt:
Microsoft.Dynamics.CRM.+<Logischer Name der Entität>.

Wie im Abschnitt Gebundene Aktionen angezeigt, ist der Target-Parameter für AddToQueue Action eine Aktivität. Aber da alle Aktivitäten von activitypointer EntityType erben, müssen Sie folgende Eigenschaft in der Entität JSON aufnehmen, um zu definieren, dass der Typ der Entität ein Buchstabe ist: "@odata.type": "Microsoft.Dynamics.CRM.letter".

Zwei weitere Beispiele sind AddMembersTeam Action und RemoveMembersTeam Action weil der Members Parameter eine Sammlung von systemuser EntityType die den ownerid Primärschlüssel von principal EntityType erben. Wenn Sie die folgende JSON ausführen, um einem einzelnen Benutzer in der Sammlung anzuzeigen, ist es klar, dass die Entität ein Systemnutzer und nicht ein team EntityType ist, der auch von Haupt-Entitätstyp erbt.

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

Wenn Sie nicht den Typ der Entität in dieser Situation angeben, erhalten Sie möglicherweise folgenden Fehler: "EdmEntityObject passed should have the key property value set.".

Siehe auch

Internet-API-Funktionen- und Aktionen-Beispiel (C#)
Beispiele von Web API-Funktionen und Aktionen (clientseitiges JavaScript)
Vorgänge mithilfe der Web-API ausführen
HTTP-Anforderungen verfassen und Fehler beheben
Datenabfrage mit Web-API
Erstellen einer Entität mithilfe des Web-API
Abrufen einer Entität mithilfe des Web-API
Entitäten aktualisieren und löschen mithilfe der Web API
Entitäten zuordnen und Zuordnungen aufheben mithilfe der Web API
Nutzen von Web-API-Funktionen
Ausführen von Batchbetrieben mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit Web API
Bedingte Vorgänge mithilfe der Web-API ausführen

Microsoft Dynamics 365

© 2017 Microsoft. Alle Rechte vorbehalten. Copyright