Freigeben über

Verwenden von Web-API-Aktionen

Aktionen und Funktionen stellen wiederverwendbare Vorgänge dar, die Sie mithilfe der Web-API ausführen können. Verwenden Sie eine POST Anforderung mit Aktionen, die in Web API Action Reference der Liste aufgeführt sind, um Vorgänge auszuführen, die Nebenwirkungen haben. Sie können auch benutzerdefinierte Aktionen definieren. Weitere Informationen: Erstellen Sie Eigene Nachrichten.

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

Ungebundene Aktionen

Der folgende XML-Code ist die Definition der Merge Aktion, die im $metadata-Dienstdokument 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 Merge Aktion entspricht der MergeRequest Verwendung des SDK für .NET. Verwenden Sie diese Aktion, um ein Paar doppelter Datensätze zusammenzuführen. Diese Aktion enthält keinen Rückgabewert. Wenn er erfolgreich ist, ist der Vorgang abgeschlossen.

Das folgende Beispiel ist die HTTP-Anforderung und die Antwort, um die Merge Aktion für zwei Kontodatensätze aufzurufen.

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

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

Verknüpfte Aktionen

Es gibt zwei Möglichkeiten, eine Aktion zu binden. Die häufigste Methode besteht darin, dass die Aktion an eine Entität gebunden werden soll. Weniger häufig kann sie auch an eine Entitätssammlung gebunden werden.

In dem CSDL-$metadata-Dokument, wenn ein Action Element eine gebundene Aktion darstellt, hat es ein IsBound Attribut mit dem Wert true. Das erste Parameter in der Aktion definierte Element stellt die Entität dar, an die der Vorgang gebunden ist. Wenn das Type Attribut des Parameters eine Auflistung ist, wird der Vorgang an eine Auflistung von Entitäten gebunden.

Beim Aufrufen einer gebundenen Funktion müssen Sie den vollständigen Namen der Funktion einschließlich des Microsoft.Dynamics.CRM Namespaces einschließen. 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

Ein Beispiel für eine Aktion, die an eine Entität gebunden ist, ist die folgende Definition der Aktion, die in der CSDL als AddToQueue dargestellt 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 entitätsgebundene Aktion entspricht dem AddToQueueRequest vom SDK für .NET verwendeten. In der Web-API ist diese Aktion an den Entitätstyp gebunden, der die Eigenschaft AddToQueueRequestDestinationQueueId darstellt. Diese Aktion akzeptiert mehrere weitere Parameter und gibt einen AddToQueueResponse komplexen Typ zurück, der dem AddToQueueResponse vom SDK für .NET zurückgegebenen Typ entspricht. Wenn eine Aktion einen komplexen Typ zurückgibt, wird die Definition des komplexen Typs direkt über der Aktion in der CSDL angezeigt.

Eine an eine Entität gebundene Aktion muss mithilfe eines URI aufgerufen werden, um den ersten Parameterwert festzulegen. Sie können ihn nicht als benannten Parameterwert 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 (mscrm.crmbaseentity) ist, müssen Sie den Typ des Objekts explizit deklarieren, indem Sie den @odata.type Eigenschaftswert des vollständigen Namens der Entität einschließlich des Microsoft.Dynamics.CRM Namespaces verwenden. In diesem Fall Microsoft.Dynamics.CRM.letter. Weitere Informationen: Angeben des Entitätsparametertyps

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

Aktionen, die an eine Tabellensammlung gebunden sind

Es ist weniger häufig, Aktionen zu finden, die an eine Entitätssammlung gebunden sind. Es folgen einige, die Sie möglicherweise finden:

CreateException

DeliverIncomingEmail

ExportTranslation

ValidateSavedQuery

FulfillSalesOrder in Dynamics 365 for Sales

CreateMultiple

UpdateMultiple

Als Beispiel für eine Aktion, die an eine Entitätsauflistung gebunden ist, ist folgendes die Definition der ExportTranslation Aktion, die in der CSDL-$metadata dargestellt 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 an den Entitätstyp solution gebunden. Anstatt jedoch einen Wert an die Anforderung zu übergeben, wendet die Bindung der Entitätensammlung einfach die Einschränkung an, dass der URI der Anforderung den Pfad zum angegebenen Entitätensatz enthalten muss.

Das folgende Beispiel zeigt die Verwendung der ExportTranslation Aktion, die eine Binärdatei exportiert, die Daten zu lokalisierbaren Zeichenfolgenwerten enthält, die 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 benutzerdefinierte Aktion kann eine benutzerdefinierte API oder eine benutzerdefinierte Prozessaktion sein. Egal, wie sie erstellt wird, es gibt dazu einen entsprechenden Vorgang, den Sie verwenden können. Bei benutzerdefinierter API kann der Vorgang eine Funktion sein. Weitere Informationen: Erstellen eigener Nachrichten

Das folgende Beispiel ist für eine benutzerdefinierte Prozessaktion vorgesehen.

Beispiel für eine benutzerdefinierte Aktion: Hinzufügen einer Notiz zu einem Kontakt

Angenommen, Sie möchten eine benutzerdefinierte Aktion erstellen, die einem bestimmten Kontakt eine neue Notiz hinzufügt. Sie können eine benutzerdefinierte Aktion erstellen, die an die Kontaktentität mit den folgenden Eigenschaften gebunden ist.

UI-Beschriftung Wert
Prozessname NotizZuKontaktHinzufügen
Eindeutiger Name neue_NotizZuKontaktHinzufügen
Entität Kontakt
Kategorie Maßnahme

Prozessargumente

Name Typ Erforderlich Richtung
NotizTitel String Erforderlich Input
Hinweistext String Erforderlich Input
NoteReference EntityReference Erforderlich Output

Schritte

Name Schritt-Typ Description
Erstellen der Notiz Datensatz erstellen Title = {NoteTitle(Arguments)}
Note Body = {NoteText(Arguments)}
Bezug = {Contact{Contact}}
Zurückgeben eines Verweises auf die Notiz Wert zuweisen NoteReference-Wert = {Notiz(Erstellen Sie die Notiz (Notiz))}

Nachdem Sie die benutzerdefinierte Aktion veröffentlicht und aktiviert haben, finden Sie beim Herunterladen der CSDL 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 die Antwort aufgerufen werden, die zurückgegeben wird, wenn dies erfolgreich ist.

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

Angeben des Tabellentypparameters

Wenn eine Aktion eine Entität als Parameter erfordert und der Entitätstyp mehrdeutig ist, müssen Sie die @odata.type Eigenschaft verwenden, um den Entitätstyp anzugeben. Der Wert dieser Eigenschaft ist der vollqualifizierte Name der Entität, die diesem Muster folgt: Microsoft.Dynamics.CRM.+<logischer Entitätsname>.

Wie im abschnitt "Gebundene Aktionen " oben gezeigt, ist der Target Parameter für die AddToQueue Aktion 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 AddMembersTeam und RemoveMembersTeam Aktionen, da der Members Parameter eine Sammlung von systemuser Entitätstypen ist, die den Primärschlüssel vom ownerid Entitätstyp principal erben. Wenn Sie den folgenden JSON-Code übergeben, um einen einzelnen Systembenutzer in der Auflistung darzustellen, ist klar, dass es sich bei der Entität um einen Systembenutzer und nicht um einen team Entitätstyp handelt, der ebenfalls vom Prinzipalentitätstyp erbt.

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

Wenn Sie den Entitätstyp in dieser Situation nicht angeben, können Sie die folgende Fehlermeldung erhalten: "EdmEntityObject passed should have the key property value set."

Siehe auch

Web-API-Aktionen
Beispiel für Internet-API-Funktionen- und Aktionen (C#)
Beispiele von Web API-Funktionen und Aktionen (clientseitiges JavaScript)
Ausführen von Vorgängen mithilfe der Web-API
HTTP-Anforderungen verfassen und Fehler beheben
Datenabfrage mit Web-API
Erstellen einer Tabellenzeile mithilfe der Web-API
Abrufen einer Tabellenzeile über die Web-API
Tabellenzeilen über die Web-API aktualisieren und löschen
Zuordnen und Aufheben der Zuordnung von Tabellenzeilen über die Web-API
Web-API-Funktionen verwenden
Ausführen von Batchvorgängen mithilfe der Web-API
Annehmen eines anderen Benutzerkontos mit der Web-API
Bedingte Vorgänge mithilfe der Web-API ausführen

  • Last updated on