Freigeben über

Verwenden Sie Webhooks zum Erstellen externer Handler für Serverereignisse

Verwenden Sie Webhooks, um Microsoft Dataverse-Serverereignisse an eine externe Webanwendung zu senden. In diesem Artikel wird erläutert, welche Anforderungsdaten von Dataverse gesendet werden und wie Webhooks Ihnen dabei helfen, externe Handler für Serverereignisse zu erstellen.

Mithilfe von Webhooks können Entwickler und ISVs Dataverse-Daten in ihren eigenen benutzerdefinierten Code integrieren, der in externen Diensten gehostet wird. Mit dem Webhook-Modell können Sie Ihren Endpunkt sichern, indem Sie einen Authentifizierungsheader oder Abfrage-Zeichenfolgenparameterschlüssel verwenden. Dieser Ansatz ist einfacher als das SAS-Authentifizierungsmodell, das Sie derzeit für die Azure Service Bus-Integration verwenden können.

Beachten Sie bei der Entscheidung zwischen dem Webhook-Modell und der Azure Service Bus-Integration die folgenden Punkte:

  • Azure Service Bus eignet sich für die hochskalierte Verarbeitung und bietet einen vollständigen Warteschlangenmechanismus, wenn Dataverse viele Ereignisse weiterleitet.
  • Webhooks können nur bis zu dem Punkt skaliert werden, an dem Ihr gehosteter Webdienst die Nachrichten verarbeiten kann.
  • Webhooks aktivieren synchrone und asynchrone Schritte. Azure Service Bus ermöglicht nur asynchrone Schritte.
  • Webhooks senden POST-Anforderungen mit JSON-Nutzlast und können von allen Programmiersprachen oder Webanwendungen an jedem beliebigen Ort konsumiert werden.
  • Sowohl Webhooks als auch Azure Service Bus können über ein Plug-In oder eine benutzerdefinierte Workflowaktivität aufgerufen werden.

Erste Schritte

Die Verwendung von Webhooks umfasst drei Teile:

  • Erstellen oder Konfigurieren eines Services zum Konsumieren von Webhook-Anforderungen.
  • Webhook-Schritt auf dem Dataverse-Dienst registrieren.
  • Aufrufen des Webhooks von einem Plug-In oder einer benutzerdefinierten Workflowaktivität.

Beginnen Sie mit der Registrierung eines TestwebHook

Um zu verstehen, wie Sie einen Dienst erstellen und konfigurieren, um eine WebHook-Anforderung von Dataverse zu nutzen, lernen Sie zunächst, wie Sie einen WebHook registrieren. Weitere Informationen finden Sie unter Registrieren eines WebHook.

Nachdem Sie ein Beispiel-WebHook registriert haben, verwenden Sie eine Anforderungsprotokollierungswebsite, um die übergebenen Kontextdaten zu untersuchen. Weitere Informationen finden Sie unter Testen der WebHook-Registrierung mit der Anforderungsprotokollierungsseite.

Tipp

Wenn Sie die Schritte zum Registrieren eines WebHook-Tests ausführen und die übergebenen Kontextdaten untersuchen, können Sie die restlichen Informationen in diesem Thema leichter verstehen. Führen Sie diese Schritte aus, und kehren Sie zu diesem Thema zurück.

Erstellen oder Konfigurieren eines Diensts für die Nutzung von WebHook-Anforderungen

Webhooks sind einfach ein Muster, das Sie mit einer vielzahl von Technologien anwenden können. Es gibt keine erforderlichen Frameworks, Plattformen oder Programmiersprachen, die Sie verwenden müssen. Nutzen Sie Ihr Wissen und Ihre Fähigkeiten, um die entsprechende Lösung bereitzustellen.

Azure Functions bieten eine hervorragende Möglichkeit, eine Lösung mithilfe von Webhooks bereitzustellen, aber es ist keine Anforderung. Dieser Abschnitt enthält keine Anleitungen zu einer bestimmten Lösung. Stattdessen werden die Daten beschrieben, die Dataverse an Ihren Dienst übergibt, mit denen Ihr Dienst Wert hinzufügen kann.

Wie in der Test-WebHook-Registrierung mit Anforderungsprotokollierungswebsite gezeigt, können Sie einen WebHook-Testschritt registrieren und die Anforderungsprotokollierungswebsite verwenden, um die spezifischen Arten von Daten zu erfassen, die Ihre Anwendung verarbeiten kann.

An einen Service übergebene Daten

Die Anforderung enthält drei Arten von Daten: Abfragezeichenfolge, Kopfzeilendaten und Anforderungstext.

Abfragezeichenfolge

Die einzigen Daten, die Sie als Abfragezeichenfolge übergeben, sind die Authentifizierungswerte, wenn Sie den WebHook so konfigurieren, dass die WebhookKey - oder HttpQueryString-Optionen verwendet werden, wie in den Authentifizierungsoptionen beschrieben.

Kopfzeilendaten

Wenn Sie die HttpHeader-Authentifizierungsoption auswählen, verwenden Sie die Schlüssel-Wert-Paare, die Ihr Dienst benötigt.

Sie können davon ausgehen, dass Ihr Dienst die folgenden Daten empfängt:

Key Wertbeschreibung
x-ms-dynamics-organization Der Domänenname der Umgebung, die die Anforderung sendet
x-ms-dynamics-entity-name Der logische Name der Tabelle, die in den Ausführungskontextdaten übergeben wird.
x-ms-dynamics-request-name Der Name des Ereignisses, für das der WebHook-Schritt registriert wurde.
x-ms-correlation-request-id Eindeutiger Bezeichner für die Nachverfolgung eines beliebigen Erweiterungstyps. Die Plattform verwendet diese Eigenschaft zur Vermeidung von Endlosschleifen. In den meisten Fällen können Sie diese Eigenschaft ignorieren. Beim Arbeiten mit technischem Support kann dieser Wert verwendet werden, um Telemetrie abzufragen, um zu verstehen, was während des gesamten Vorgangs aufgetreten ist.
x-ms-dynamics-msg-size-exceeded Wird nur gesendet, wenn die HTTP-Nutzlastgröße 256 KB überschreitet.

Anforderungstext

Der Text enthält eine Zeichenfolge, die den JSON-Wert einer Instanz der RemoteExecutionContext Klasse darstellt. Dies sind die gleichen Daten, die an Azure Service Bus-Integrationen übergeben werden.

Der Service, den Sie erstellen, muss diese Daten analysieren, um für Ihren Service die relevanten Informationen zu extrahieren, um dessen Funktion bereitzustellen. Wie Sie diese Daten analysieren, hängt von der verwendeten Technologie und Ihren Vorlieben ab.

Das folgende Beispiel zeigt die serialisierten JSON-Daten, die für einen Schritt übergeben werden, der mit den folgenden Eigenschaften registriert wurde:

Eigentum Description
Meldung Update
Primäre Entität Kontakt
Sekundäre Entität none
Filter-Attribute firstname,lastname
Im Kontext des Benutzers ausführen Aufrufender Benutzer
Ausführungs-Reihenfolge 1
Ereignis-Pipeline-Phase der Ausführung PostOperation
Ausführungs-Modus Asynchron 
{
    "BusinessUnitId": "e2b9dd85-e89e-e711-8122-000d3aa2331c",
    "CorrelationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
    "Depth": 1,
    "InitiatingUserId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
    "InputParameters": [{
        "key": "Target",
        "value": {
            "__type": "Entity:http:\/\/schemas.microsoft.com\/xrm\/2011\/Contracts",
            "Attributes": [{
                "key": "firstname",
                "value": "James"
            }, {
                "key": "contactid",
                "value": "6d81597f-0f9f-e711-8122-000d3aa2331c"
            }, {
                "key": "fullname",
                "value": "James Glynn (sample)"
            }, {
                "key": "yomifullname",
                "value": "James Glynn (sample)"
            }, {
                "key": "modifiedon",
                "value": "\/Date(1506384247000)\/"
            }, {
                "key": "modifiedby",
                "value": {
                    "__type": "EntityReference:http:\/\/schemas.microsoft.com\/xrm\/2011\/Contracts",
                    "Id": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
                    "KeyAttributes": [],
                    "LogicalName": "systemuser",
                    "Name": null,
                    "RowVersion": null
                }
            }, {
                "key": "modifiedonbehalfby",
                "value": null
            }],
            "EntityState": null,
            "FormattedValues": [],
            "Id": "6d81597f-0f9f-e711-8122-000d3aa2331c",
            "KeyAttributes": [],
            "LogicalName": "contact",
            "RelatedEntities": [],
            "RowVersion": null
        }
    }],
    "IsExecutingOffline": false,
    "IsInTransaction": false,
    "IsOfflinePlayback": false,
    "IsolationMode": 1,
    "MessageName": "Update",
    "Mode": 1,
    "OperationCreatedOn": "\/Date(1506409448000-0700)\/",
    "OperationId": "4af10637-4ea2-e711-8122-000d3aa2331c",
    "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
    "OrganizationName": "OrgName",
    "OutputParameters": [],
    "OwningExtension": {
        "Id": "75417616-4ea2-e711-8122-000d3aa2331c",
        "KeyAttributes": [],
        "LogicalName": "sdkmessageprocessingstep",
        "Name": null,
        "RowVersion": null
    },
    "ParentContext": {
        "BusinessUnitId": "e2b9dd85-e89e-e711-8122-000d3aa2331c",
        "CorrelationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
        "Depth": 1,
        "InitiatingUserId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
        "InputParameters": [{
            "key": "Target",
            "value": {
                "__type": "Entity:http:\/\/schemas.microsoft.com\/xrm\/2011\/Contracts",
                "Attributes": [{
                    "key": "firstname",
                    "value": "James"
                }, {
                    "key": "contactid",
                    "value": "6d81597f-0f9f-e711-8122-000d3aa2331c"
                }],
                "EntityState": null,
                "FormattedValues": [],
                "Id": "6d81597f-0f9f-e711-8122-000d3aa2331c",
                "KeyAttributes": [],
                "LogicalName": "contact",
                "RelatedEntities": [],
                "RowVersion": null
            }
        }, {
            "key": "SuppressDuplicateDetection",
            "value": false
        }],
        "IsExecutingOffline": false,
        "IsInTransaction": false,
        "IsOfflinePlayback": false,
        "IsolationMode": 1,
        "MessageName": "Update",
        "Mode": 1,
        "OperationCreatedOn": "\/Date(1506409448000-0700)\/",
        "OperationId": "4af10637-4ea2-e711-8122-000d3aa2331c",
        "OrganizationId": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
        "OrganizationName": "OneFarm",
        "OutputParameters": [],
        "OwningExtension": {
            "Id": "75417616-4ea2-e711-8122-000d3aa2331c",
            "KeyAttributes": [],
            "LogicalName": "sdkmessageprocessingstep",
            "Name": null,
            "RowVersion": null
        },
        "ParentContext": null,
        "PostEntityImages": [],
        "PreEntityImages": [],
        "PrimaryEntityId": "6d81597f-0f9f-e711-8122-000d3aa2331c",
        "PrimaryEntityName": "contact",
        "RequestId": null,
        "SecondaryEntityName": "none",
        "SharedVariables": [{
            "key": "ChangedEntityTypes",
            "value": [{
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "feedback",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "contract",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "salesorder",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "connection",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "socialactivity",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "postfollow",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "incident",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "invoice",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "entitlement",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "lead",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "opportunity",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "quote",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "socialprofile",
                "value": "Update"
            }, {
                "__type": "KeyValuePairOfstringstring:#System.Collections.Generic",
                "key": "contact",
                "value": "Update"
            }]
        }],
        "Stage": 30,
        "UserId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff"
    },
    "PostEntityImages": [{
        "key": "AsynchronousStepPrimaryName",
        "value": {
            "Attributes": [{
                "key": "fullname",
                "value": "James Glynn (sample)"
            }, {
                "key": "contactid",
                "value": "6d81597f-0f9f-e711-8122-000d3aa2331c"
            }],
            "EntityState": null,
            "FormattedValues": [],
            "Id": "6d81597f-0f9f-e711-8122-000d3aa2331c",
            "KeyAttributes": [],
            "LogicalName": "contact",
            "RelatedEntities": [],
            "RowVersion": null
        }
    }],
    "PreEntityImages": [],
    "PrimaryEntityId": "6d81597f-0f9f-e711-8122-000d3aa2331c",
    "PrimaryEntityName": "contact",
    "RequestId": null,
    "SecondaryEntityName": "none",
    "SharedVariables": [],
    "Stage": 40,
    "UserId": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff"
}

Von Bedeutung

Wenn die Größe der gesamten HTTP-Nutzlast 256 KB überschreitet, wird der x-ms-dynamics-msg-size-exceeded Header eingeschlossen, und die folgenden RemoteExecutionContext Eigenschaften werden entfernt:

Einige Vorgänge enthalten diese Eigenschaften nicht.

Aufrufen eines WebHook aus einem Plug-In oder einer Workflowaktivität

Da ein WebHook eine Art Dienstendpunkt ist, können Sie ihn aufrufen, ohne einen Schritt mithilfe eines Plug-Ins oder einer Workflowaktivität zu registrieren. Dieser Ansatz funktioniert auf die gleiche Weise wie für einen Azure Service Bus-Endpunkt. Sie müssen die ServiceEndpointId für die IServiceEndpointNotificationService-Schnittstelle bereitstellen. Weitere Informationen finden Sie in den folgenden Azure Service Bus-Beispielen:

Problembehandlung bei WebHook-Registrierungen

Webhooks sind verhältnismäßig einfach. Der Dienst sendet die Anforderung und wertet die Antwort aus. Das System kann keine Daten analysieren, die mit dem Textkörper der Antwort zurückgegeben werden. Er betrachtet nur den Antwortwert StatusCode .

Das Timeout beträgt 60 Sekunden. Wenn vor dem Timeoutzeitraum keine Antwort zurückgegeben wird oder der Antwortwert StatusCode nicht innerhalb des 2xx Bereichs liegt, um den Erfolg anzuzeigen, schlägt der Vorgang fehl. Dies gilt nicht, wenn der zurückgegebene Fehler in folgender Tabelle enthalten ist:

StatusCode Description
502 Ungültiges Gateway
503 Dienst nicht verfügbar
504 Gateway-Timeout

Diese Fehler weisen auf ein Netzwerkproblem hin, das möglicherweise mit einem anderen Versuch aufgelöst werden kann. Der WebHook-Dienst unternimmt nur einen weiteren Versuch, wenn diese Fehlercodes zurückgegeben werden.

Asynchrone Webhooks

Wenn Sie Ihren Web-Hook für die asynchrone Ausführung registrieren, können Sie den Systemauftrag auf Details zum Fehler überprüfen. Weitere Informationen finden Sie unter Fehlgeschlagene asynchrone Aufträge für einen bestimmten Schritt abfragen.

Synchrone Webhooks

Wenn Sie den synchronen Ausführungsmodus verwenden, werden alle Fehler dem Benutzer der Anwendung gemeldet. Dazu wird ein Endpunkt nicht verfügbar-Fehlerdialog angezeigt, der den Benutzer darüber informiert, dass der Webhook-Service-Endpunkt möglicherweise falsch konfiguriert oder nicht verfügbar ist. Über das Dialogfeld können Sie eine Protokolldatei herunterladen, um Details zu Fehlern zu erhalten.

Hinweis

Wenn Sie einen Webhook für einen synchronen Schritt registrieren, sendet er die Ausführungskontextdaten sofort an den konfigurierten Endpunkt. Wenn nach dem Senden der Anforderung ein Fehler auftritt, wird ein Rollback für den Datenvorgang ausgeführt, die an den konfigurierten Endpunkt gesendete Anforderung kann jedoch nicht zurückgerufen werden.

Nächste Schritte

Registrieren eines Webhooks
Testen der Webhook-Registrierung mit der Anforderungsprotokollierungs-Website

Siehe auch

Schreiben eines Plug-Ins
Registrieren eines Plug-Ins
Asynchroner Dienst in Dataverse
Beispiel: Benutzerdefiniertes Azure-fähiges Plug-In
Beispiel: Azure-fähige benutzerdefinierte Workflow-Aktivität
Azure-Funktionen
ServiceEndpoint-Tabelle
SdkMessageProcessingStep-Tabelle
Tabelle "AsynchronousOperations"
RemoteExecutionContext
IServiceEndpointNotificationService

  • Last updated on