Freigeben über

Verwenden von Web-API-Aktionen

Verwenden Sie Web-API-Aktionen, um wiederverwendbare Vorgänge auszuführen, die Nebenwirkungen in Microsoft Dataverse haben. Senden Sie eine POST Anforderung mit aktionen, die zum Web API Action Reference Ändern von Daten, Auslösen von Geschäftslogik oder Zum Aufrufen von benutzerdefinierten Prozessen aufgeführt sind. Sie können auch benutzerdefinierte Aktionen definieren. Weitere Informationen finden Sie unter Erstellen eigener Nachrichten.

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

Ungebundene Aktionen

Der folgende XML-Code zeigt 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 Klasse, wenn Sie das SDK für .NET verwenden. 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 zeigt 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 finden Sie unter Zusammenführen von Tabellenzeilen mithilfe der Web-API.

Verknüpfte Aktionen

Sie können eine Aktion an eine Entität oder an eine Entitätssammlung binden. Das Binden einer Aktion an eine Entität ist häufiger.

Im CSDL-$metadata-Dokument weist ein Action Element, das eine gebundene Aktion darstellt, ein IsBound Attribut auf.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.

Wenn Sie eine gebundene Funktion aufrufen, schließen Sie den vollständigen Namen der Funktion einschließlich des Microsoft.Dynamics.CRM Namespaces ein. 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

Die Definition der AddToQueue-Aktion und des AddToQueueResponse-komplexen Typs in dem folgenden Beispiel in der CSDL zeigt eine an eine Entität gebundene Aktion.

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

Sie müssen eine An eine Entität gebundene Aktion aufrufen, indem Sie einen URI verwenden, um den ersten Parameterwert festzulegen. Sie können ihn nicht als benannten Parameterwert festlegen.

Das folgende Beispiel zeigt, wie Sie die AddToQueue Aktion verwenden, um einer Warteschlange einen Buchstaben hinzuzufügen. 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 finden Sie unter 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. Die folgende Liste enthält einige Aktionen, 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, zeigt die folgende Definition die ExportTranslation-Aktion, die im CSDL-$Metadaten dargestellt ist.

<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, erfordert die Bindungseinschränkung für die Entitätssammlung, dass der URI der Anforderung den Pfad zum angegebenen Entitätssatz enthalten muss.

Das folgende Beispiel zeigt, wie Sie die ExportTranslation Aktion verwenden, die eine Binärdatei exportiert, die Daten zu lokalisierbaren Zeichenfolgenwerten enthält, die Sie aktualisieren können, um lokalisierbare Werte zu ändern oder hinzuzufügen. Beachten Sie, wie die gebundene Aktion der Entitätssammlung nach dem Entitätssatznamen für die Lösungsentität kommt: 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. Jede Art von benutzerdefinierter Aktion verfügt über einen entsprechenden Vorgang, den Sie verwenden können. Bei einer benutzerdefinierten API kann der Vorgang eine Funktion sein. Weitere Informationen finden Sie unter Erstellen eigener Nachrichten.

Das folgende Beispiel zeigt eine benutzerdefinierte Prozessaktion.

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, wird diese neue Aktion beim Herunterladen der CSDL 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 zeigen, 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 Typ der Entität mehrdeutig ist, verwenden Sie die @odata.type Eigenschaft, 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 " 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ätstyp ist, die seinen ownerid Primärschlüssel vom principal Entitätstyp erbt. 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