Registrieren eines WebHooks

Verwenden Sie das Plug-in Registration Tool, um einen WebHook zu registrieren. Um das Plug-in-Registrierungs-Tool zu erhalten, gehen Sie zu Dataverse Bereitstellungtools

Wählen Sie im Tool „Plug-in-Registrierung“ die Option Neuen Webhook registrieren aus.

Wenn Sie einen Webhook registrieren, müssen Sie drei Elemente zur Verfügung stellen:

Artikel	Beschreibung
Name des Dataflows	Einen eindeutigen Namen, der den WebHook beschreibt.
Endpunkt-URL	Die URL, an die Ausführungskontextinformationen gepostet werden.
Authentifizierung	Eine von drei Authentifizierungsoptionen. Für jeden Authentifizierungstyp müssen Sie die Schlüssel bereitstellen, durch die die Anforderung als legitim identifiziert wird.

Registrierte WebHooks unterstützen nur Port 80 für HTTP und Port 443 für HTTPS.

Authentifizierungsoptionen

Welche Webhook-Registrierungsauthentifizierungsoption die richtige ist und welche Werte verwendet werden müssen, hängt davon ab, was der Endpunkt erwartet. Der Besitzer des Endpunkts muss Ihnen mitteilen, was verwendet werden soll. Zum Verwenden von Webhooks mit Microsoft Dataverse muss der Endpunkt eine der folgenden Authentifizierungsoptionen zulassen:

Type	Beschreibung
HttpHeader	Enthält eine oder mehrere Schlüsselwertpaare im Header der HTTP-Anforderung. Beispiel: Key1: Value1 Key2: Value2
WebhookKey	Enthält einer Abfragezeichenfolge mithilfe code als den Schlüssel und einen Wert, der vom Endpunkt erforderlich ist. Wenn Sie den WebHook mit dem Plug-in Registration Tool registrieren, geben Sie nur den Wert ein. Beispiel: ?code=00000000-0000-0000-0000-000000000001
HttpQueryString	Enthält eine oder mehrere Schlüsselwertpaare als Zeichenfolgenparameter. Beispiel: ?Key1=Value1&Key2=Value2

Hinweis

Die Option WebhookKey ist für die Verwendung mit Azure-Funktionen hilfreich, da von der Authentifizierungsabfragezeichenfolge erwartet wird, dass sie einen Schlüsselnamen von code hat.

Alle Anforderungen an den konfigurierten Endpunkt sollten fehlschlagen, wenn die in der Anforderung übergebenen Authentifizierungsoptionen nicht übereinstimmen. Dafür ist der Endpunkt verantwortlich.

WebHook-Registrierungen abfragen

WebHook-Registrierungen werden in der ServiceEndpoint-Tabelle gespeichert und haben einen Vertrag-Wert von 8.

Details zu den registrierten Webhooks finden Sie durch Abfrage der Tabelle ServiceEndpoint.

Web-API:

GET [organization URI]/api/data/v9.0/serviceendpoints?$filter=contract eq 8&$select= serviceendpointid,name,authtype,url

Weitere Informationen: Daten mit der Web-API abfragen

FetchXml:

<fetch>
  <entity name="serviceendpoint" >
    <attribute name="serviceendpointid" />
    <attribute name="name" />
    <attribute name="authtype" />
    <attribute name="url" />
    <filter>
      <condition attribute="contract" operator="eq" value="8" />
    </filter>
  </entity>
</fetch> 

Weitere Informationen: FetchXML zum Abrufen von Daten verwenden

Informationen zu den festgelegten Authentifizierungswerten sind in der AuthValue-Eigenschaft gespeichert und können nicht abgerufen werden.

Registrieren eines Schritts für einen WebHook

Das Registrieren eines Schritts für einen WebHook ist wie das Registrieren eines Schritts für ein Plug-In. Der Hauptunterschied ist, dass Sie keine Konfigurationsinformationen angeben können.

Genau wie bei einem Plug-In geben Sie die Nachricht und ggf. Informationen über Tabellen an. Sie können auch angeben, wo in der Ereignis-Pipeline der WebHook ausgeführt werden soll, den Ausführungsmodus und ob eine AsyncOperation gelöscht werden soll, wenn die Operation erfolgreich ist.

Informationen zu Schrittname und Beschreibung werden basierend auf den ausgewählten Optionen automatisch ausgefüllt, Sie können die Daten jedoch ändern. Wenn Sie keine Filterattribute für eine Nachricht festlegen, die diese unterstützt, werden Sie zwecks optimalem Leistungsverfahren dazu aufgefordert.

Ausführungsmodus und Debugging Ihrer WebHook-Registrierung

Ihre Wahl bei der Registrierung des Webhooks ändert die Erfahrung, die Sie beim Debuggen machen, wenn etwas nicht funktioniert.

Asynchroner Modus

Wenn Sie den asynchronen Ausführungsmodus verwenden, wird ein Systemauftrag (AsyncOperation) erstellt, um den Erfolg oder Misserfolg der Operation zu erfassen. Wenn Sie sich dafür entscheiden, den Systemauftrag bei Erfolg zu löschen, sparen Sie Speicherplatz in der Datenbank.

Alle Fehler, die auftreten, werden in Systemaufträgen aufgezeichnet. In der Web-Anwendung können Sie zu Einstellungen > System > System Jobs gehen, um den Status aller Webhooks zu überprüfen. Es gibt einen Statusgrund-Wert vom Typ Fehler. Öffnen Sie den fehlgeschlagenen System-Job, um Details zu finden, die beschreiben, warum der Job fehlgeschlagen ist.

Fehlgeschlagene asynchrone Aufträge für einen gegebenen Schritt abfragen

Wenn Sie die sdkmessageprocessingstepid eines bestimmten Steps kennen, können Sie die AsynchronousOperations Table auf Fehler abfragen. Mit dem OwningExtensionId-Wert können Sie die Ergebnisse nach einem bestimmten registrierten Schritt filtern. Die folgenden Beispiele nutzen <stepid> für die sdkmessageprocessingstepid des nächsten Schritts.

Tipp

Um die sdkmessageprocessingstepid eines bestimmten Schritts zu erhalten, siehe Abfrage der für einen WebHook registrierten Schritte unten.

Web-API:

GET [organization URI]/api/data/v9.0/asyncoperations?$orderby=completedon desc&$filter=statuscode eq 31 and _owningextensionid_value eq @stepid&$select=name,friendlymessage,errorcode,message,completedon?@stepid=<stepid>

Weitere Informationen: Daten mit der Web-API abfragen

FetchXML:

<fetch>
  <entity name="asyncoperation" >
    <attribute name="name" />
        <attribute name="friendlymessage" />
    <attribute name="errorcode" />
    <attribute name="message" />
    <attribute name="completedon" />     
    <filter>
      <condition attribute="owningextensionid" operator="eq" value="<stepid>" />
    </filter>
    <order attribute="completedon" descending="true" />
  </entity>
</fetch>

Weitere Informationen: FetchXML zum Abrufen von Daten verwenden

Synchroner Modus

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. Im Dialogfeld können Sie eine Protokolldatei mit Informationen zu etwaigen Fehlern herunterladen.

Hinweis

Sie sollten den synchronen Modus verwenden, wenn es wichtig ist, dass der durch den WebHook ausgelöste Vorgang sofort stattfindet oder wenn Sie wollen, dass die gesamte Transaktion fehlschlägt, wenn die WebHook-Nutzlast nicht vom Dienst empfangen wird. Eine einfache WebHook-Schrittregistrierung bietet begrenzte Möglichkeiten zur Verwaltung von Fehlern, aber Sie können Webhooks auch über Plug-Ins und Workflowaktivitäten aufrufen, wenn Sie mehr Steuerelemente benötigen. Mehr Informationen: Aufrufen eines WebHooks von einem Plug-In oder einer Workflow-Aktivität.

Für einen WebHook registrierte Abfrageschritte

Daten für registrierte Webhooks befinden sich in der SdkMessageProcessingStep-Tabelle.

Sie können die für einen bestimmten WebHook registrierten Schritte abfragen, wenn Sie die serviceendpointid für den WebHook kennen. Siehe Abfrage WebHook-Registrierungen für eine Abfrage, um die ID für einen registrierten WebHook zu erhalten.

Web-API:

Sie können diese Web-API-Abfrage verwenden, wobei <id> die ServiceEndpointId des WebHooks ist:

GET [organization URI]/api/data/v9.0/serviceendpoints(@id)/serviceendpoint_sdkmessageprocessingstep?$select=sdkmessageprocessingstepid,name,description,asyncautodelete,filteringattributes,mode,stage?@id=<id>

Weitere Informationen über den registrierten Schritt erhalten Sie, wenn Sie die Web-API-Abfrage nutzen, bei der die <stepid> die SdkMessageProcessingStepId für den Schritt ist:

GET [organization URI]/api/data/v9.0/sdkmessageprocessingsteps(@id)?$select=name,description,filteringattributes,asyncautodelete,mode,stage&$expand=plugintypeid($select=friendlyname),eventhandler_serviceendpoint($select=name),sdkmessagefilterid($select=primaryobjecttypecode),sdkmessageid($select=name)?@id=<stepid>

FetchXML:

Sie können diese FetchXML verwenden, um die gleichen Informationen in einer Abfrage zu erhalten, wobei <serviceendpointid> die ID des WebHooks ist:

<fetch>
  <entity name="sdkmessageprocessingstep" >
    <attribute name="name" />
    <attribute name="filteringattributes" />
    <attribute name="stage" />
    <attribute name="asyncautodeletename" />
    <attribute name="description" />
    <attribute name="mode" />
    <link-entity name="serviceendpoint" from="serviceendpointid" to="eventhandler" link-type="inner" alias="endpnt" >
      <attribute name="name" />
      <filter>
        <condition attribute="serviceendpointid" operator="eq" value="<serviceendpointid>" />
      </filter>
    </link-entity>
    <link-entity name="sdkmessagefilter" from="sdkmessagefilterid" to="sdkmessagefilterid" link-type="inner" alias="fltr" >
      <attribute name="primaryobjecttypecode" />
    </link-entity>
    <link-entity name="sdkmessage" from="sdkmessageid" to="sdkmessageid" link-type="inner" alias="msg" >
      <attribute name="name" />
    </link-entity>
  </entity>
</fetch>

Nächste Schritte,

Test der WebHook-Registrierung mit der Website für die Anforderungsprotokollierung
Verwenden Sie Webhooks zum Erstellen externer Handler für Serverereignisse

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