Nutzen von Web-API-Aktionen

Artikel
08/25/2023

Aktionen und Funktionen stellen wiederverwendbare Vorgänge dar, die Sie mithilfe der 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 auszuführen, die keine Nebenwirkungen haben. Sie können auch benutzerdefinierte Aktionen definieren. Weitere Informationen: Erstellen eigener Meldungen.

Aktionen werden im CSDL $metadata Dokument definiert. Weitere Informationen finden Sie unter Web API-Aktionen.

Ungebundene Aktionen

Folgende XML ist die Definition der Aktion Merge, die im $metadata service-Dokument dargestellt wird.

<Action Name="Merge">
   <Parameter Name="Target" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="Subordinate" 
      Type="mscrm.crmbaseentity" 
      Nullable="false" />
   <Parameter Name="UpdateContent" 
      Type="mscrm.crmbaseentity" />
   <Parameter Name="PerformParentingChecks" 
      Type="Edm.Boolean" 
      Nullable="false" />
</Action>

Die Aktion Merge entspricht MergeRequest, wobei das SDK für .NET verwendet wird. Verwenden Sie diese Aktion, um ein Paar doppelter Datensätze zusammenzuführen. Diese Aktion umfasst aber keinen Rückgabewert. Wenn der Vorgang erfolgreich ausgeführt wird, ist er abgeschlossen.

Das folgende Beispiel ist die HTTP-Anforderung und -Antwort zum Aufrufen der Aktion Merge für zwei Kontodatensätze.

Anforderung:

POST [Organization URI]/api/data/v9.2/Merge HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
  "Target": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "cc1e2c4a-e577-ec11-8d21-000d3a554dcd"
  },
  "Subordinate": {
    "@odata.type": "Microsoft.Dynamics.CRM.account",
    "accountid": "e408fa45-3a70-ec11-8943-00224823561e"
  },
  "PerformParentingChecks": false
}

Antwort:

HTTP/1.1 204 No Content
OData-Version: 4.0

Mehr Informationen: Zusammenführen von Tabellenzeilen mithilfe der Web-API.

Gebundene Aktionen

Es gibt zwei Möglichkeiten, wie eine Aktion gebunden werden kann. Der allgemeinste Weg ist der, dass die Aktion an eine Entität gebunden wird. Seltener kann sie auch an eine Sammlung von Entitäten gebunden sein.

Im CSDL-$metadata-Dokument, 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.

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

An eine Tabelle gebundene Aktionen

Als Beispiel für eine Aktion, die an eine Entität gebunden ist, folgt die Definition der Aktion AddToQueue, die in der CSDL angegeben wird:

 <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 an eine Entität gebundene Aktion entspricht der vom SDK für .NET verwendeten AddToQueueRequest. In der Web-API ist diese Aktion an den Entitätstyp queue gebunden, der die Eigenschaft AddToQueueRequest darstellt.DestinationQueueId anzugeben. Diese Aktion akzeptiert mehrere weitere Parameter und gibt eine AddToQueueResponse komplexen Typs zurück, der der AddToQueueResponse entspricht, die vom SDK für .NET zurückgegeben wird. Wenn eine Aktion einen komplexen Datentyp zurückgibt, so wird dessen komplexer Typ direkt über der Definition der Aktion in CSDL angezeigt.

Eine an eine Entität gebundene Aktion muss über einen URI aufgerufen werden, um den ersten Parameterwert festzulegen. Sie können es nicht als Parameterwert mit Namen festlegen.

Das folgende Beispiel zeigt die Verwendung der Aktion AddToQueue zum Hinzufügen eines Schreibens in eine Warteschlange. Da der Typ des Target-Parametertyps nicht spezifisch ist (mscrm.crmbaseentity), müssen Sie explizit den Typ des Objekts deklarieren, indem Sie den Eigenschaftswert @odata.type des vollständigen Namens der Entität verwenden, einschließlich des Microsoft.Dynamics.CRM Namespace. In diesem Fall: Microsoft.Dynamics.CRM.letter. Weitere Informationen: Entitätsparametertyp angeben

Anforderung:

POST [Organization URI]/api/data/v9.2/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": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.AddToQueueResponse",
 "QueueItemId": "5aae8258-4878-e511-80d4-00155d2a68d1"
}

An eine Tabellensammlung gebundene Aktionen

Es ist seltener, dass Aktionen an eine Entitätssammlung gebunden sind. Die folgenden sind möglicherweise vorhanden:

FulfillSalesOrder in Dynamics 365 for Sales

CreateMultiple

UpdateMultiple

Als Beispiel für eine Aktion, die an eine Entitätssammlung gebunden ist, folgt die Definition der Aktion ExportTranslation, die in der CSDL $metadata angegeben wird:

<ComplexType Name="ExportTranslationResponse">
   <Property Name="ExportTranslationFile" 
    Type="Edm.Binary" />
</ComplexType>
<Action Name="ExportTranslation" 
    IsBound="true">
   <Parameter Name="entityset" 
    Type="Collection(mscrm.solution)" 
    Nullable="false" />
   <Parameter Name="SolutionName" 
    Type="Edm.String" 
    Nullable="false" 
    Unicode="false" />
   <ReturnType Type="mscrm.ExportTranslationResponse" 
    Nullable="false" />
</Action>

Diese an eine Entitätssammlung gebundene Aktion entspricht der vom SDK für .NET verwendeten ExportTranslationRequest. In der Web-API ist diese Aktion aber an den Entitätstyp solution gebunden. Aber anstatt einen Wert an die Anfrage zu übergeben, wendet die Entitätssammlungsbindung einfach die Einschränkung an, dass der URI der Anfrage den Pfad zu der festgelegten Entitätsmenge enthalten muss.

Das folgende Beispiel zeigt die Verwendung der Aktion ExportTranslation, bei der eine Binärdatei exportiert wird, die Daten über lokalisierbare Zeichenfolgenwerte enthält, die dann aktualisiert werden können, um lokalisierbare Werte zu ändern oder hinzuzufügen. Beachten Sie aber, wie der Aktion „Entitätssammlung gebunden“ der Name des Entitätssatzes für die Lösungsentität vorangestellt wird: solutions.

Anforderung:

POST [Organization URI]/api/data/v9.2/solutions/Microsoft.Dynamics.CRM.ExportTranslation HTTP/1.1
Accept: application/json
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "SolutionName":"MySolution"
}

Antwort:

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

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.ExportTranslationResponse",
    "ExportTranslationFile": "[Binary data Removed for brevity]"
}

Nutzen einer benutzerdefinierten Aktion

Eine angepasste Aktion kann eine Custom-API oder Custom Process Action sein. Egal, wie sie erstellt wird, es gibt dazu einen entsprechenden Vorgang, den Sie verwenden können. Mit Custom-API kann der Vorgang eine Funktion sein. Weitere Informationen: Erstellen eigener Meldungen

Das folgende Beispiel gilt für eine benutzerdefinierte Prozessaktion.

Benutzerdefiniertes Aktionsbeispiel: Hinzufügen einer Notiz zu einem Kontakt

Angenommen, Sie möchten eine benutzerdefinierte Aktion erstellen, 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.

UI-Beschriftung	Wert
Prozessname	AddNoteToContact
Eindeutiger Name	new_AddNoteToContact
Entität	Kontakt
Kategorie	Aktion

Argumente verarbeiten

Name	Typ	Erforderlich	Richtung
Notizentitel	Zeichenfolge	Erforderlich	Eingabe
Notizentext	Zeichenfolge	Erforderlich	Eingabe
Notizenreferenz	EntityReference	Erforderlich	Ausgabe

Schritte

Name	Schritt-Typ	Beschreibung
Erstellen der Notiz	Datensatz erstellen	Titel = {NoteTitle(Arguments)} Notizen-Text = {NoteText(Arguments)} Bezug = {Contact{Contact}}
Rückgabe eines Verweises zur Notiz	Wert zuweisen	NoteReference-Wert = {Note(Create the note (Note))}

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 [Organization URI]/api/data/v9.2/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": "[Organization URI]/api/data/v9.2/$metadata#annotations/$entity",
 "annotationid": "9ad8c461-a27a-e511-80d2-00155d2a68d2"
}

Die Tabellentypparameter angeben

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 diesem Muster folgt: Microsoft.Dynamics.CRM.+<entity logical name>.

Wie im Abschnitt Gebundene Aktionen oben gezeigt, ist der Parameter Target für die Aktion AddToQueue eine Aktivität. Da aber alle Aktivitäten vom Entitätstyp activitypointer übernommen werden, muss die folgende Eigenschaft in die Entität JSON aufgenommen werden, um festzulegen, dass Typ der Entität ein Buchstabe ist: "@odata.type": "Microsoft.Dynamics.CRM.letter".

Zwei weitere Beispiele sind die Aktionen AddMembersTeam und RemoveMembersTeam, weil der Members-Parameter eine Sammlung des systemuser-Entitätstyps ist, der dann seinen ownerid-Primärschlüssel aus dem Entitätstyp principal übernimmt. Wenn Sie den folgenden JSON für einen einzelnen Systembenutzer in der Sammlung übergeben, ist es klar, dass die Entität ein Systembenutzer und kein team-Entitätstyp ist, der auch aus dem Hauptentitä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 den folgenden Fehler: "EdmEntityObject passed should have the key property value set.".

Siehe auch

Web API-Aktionen
Web-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
Abfragen von Daten mithilfe der Web-API
Erstellen einer Tabellenzeile über die Web-API
Abrufen einer Tabellenzeile über die Web-API
Aktualisieren und Löschen von Tabellenzeilen über die Web-API
Zuordnen und Aufheben der Zuordnung von Tabellenzeilen über die 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

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).

Freigeben über

Nutzen von Web-API-Aktionen

Ungebundene Aktionen

Gebundene Aktionen

An eine Tabelle gebundene Aktionen

An eine Tabellensammlung gebundene Aktionen

Nutzen einer benutzerdefinierten Aktion

Benutzerdefiniertes Aktionsbeispiel: Hinzufügen einer Notiz zu einem Kontakt

Die Tabellentypparameter angeben

Siehe auch

Zusätzliche Ressourcen