Pubblicazione di eventi Microsoft Dataverse con i webhook
Un altro metodo per pubblicare eventi da Microsoft Dataverse a un servizio esterno è registrare i webhook. Un webhook è un meccanismo basato su HTTP per la pubblicazione di eventi su qualsiasi servizio basato su API Web che si scelga. Questo metodo consente di scrivere codice personalizzato ospitato su servizi esterni come integrazione point-to-point.
Webhook e bus di servizio di Azure
Quando si considerano i meccanismi di integrazione, sono disponibili alcune opzioni. È importante considerare vari elementi quando si sceglie un metodo specifico.
Considerare l'uso del bus di servizio di Azure quando:
L'elaborazione/accodamento asincrono su larga scala è considerato un requisito.
Più sottoscrittori potrebbero necessitare di usare un dato evento Dataverse.
Si vuole gestire l'architettura di integrazione da una posizione centralizzata.
Considerare l'uso dei webhook quando:
L'elaborazione sincrona in un sistema esterno è considerata un requisito del processo (Dataverse supporta solo l'elaborazione asincrona sugli endpoint del bus di servizio).
L'operazione esterna in fase di esecuzione deve essere eseguita immediatamente.
L'intera transazione deve non riuscire se il servizio esterno non elabora correttamente il payload del webhook.
Esiste già un endpoint API Web di terze parti che si desidera usare per scopi di integrazione.
L'autenticazione con firma di accesso condiviso (SAS) non è un è consigliabile o attuabile (i webhook supportano l'autenticazione tramite intestazioni di autenticazione e chiavi di parametro della stringa di query).
Opzioni di autenticazione dei webhook
La tabella seguente descrive le tre opzioni di autenticazione disponibili per usare un messaggio webhook da un endpoint specifico.
| Tipo | Descrizione |
|---|---|
| HttpHeader | Include una o più coppie di valori chiave nell'intestazione della richiesta HTTP. Esempio: Key1: Value1, Key2: Value2 |
| WebhookKey | Include una stringa di query usando il codice come chiave e un valore richiesto dall'endpoint. Quando si registra il webhook usando Plug-in Registration Tool, immettere solo il valore. Esempio: ?code=00000000-0000-0000-0000-000000000001 |
| HttpQueryString | Include una o più coppie di valori chiave come parametri della stringa di query. Esempio: ?Key1=Value1&Key2=Value2 |
Intestazioni HTTP dei webhook
La tabella seguente mostra le intestazioni HTTP passate al servizio come parte di una chiamata webhook. È possibile usare queste intestazioni come parte del metodo di elaborazione se si sta scrivendo un nuovo processore webhook.
| Chiave | Descrizione del valore |
|---|---|
| x-request-id | Identificatore univoco della richiesta |
| x-ms-dynamics-organization | Nome del tenant che ha inviato la richiesta |
| x-ms-dynamics-entity-name | Nome logico dell'entità passato ai dati del contesto di esecuzione |
| x-ms-dynamics-request-name | Nome dell'evento per il quale è stato registrato il passaggio del webhook |
| x-ms-correlation-request-id | Identificatore univoco per il monitoraggio di qualsiasi tipo di estensione. Questa proprietà viene usata dalla piattaforma per la prevenzione del ciclo infinito. Nella maggior parte dei casi, questa proprietà si può ignorare. Questo valore si può usare quando si contatta il supporto tecnico perché può servire per eseguire query sui dati di telemetria per comprendere la natura degli eventi che si sono verificati durante l'intera operazione. |
| x-ms-dynamics-msg-size-exceeded | Inviato solo quando la dimensione del payload HTTP supera 256 KB |
Registrazione di un endpoint webhook
La registrazione dell'endpoint webhook viene eseguita in modo simile alla registrazione dell'endpoint servizio, ovvero usando Plug-in Registration Tool.
In Plug-in Registration Tool è possibile registrare un nuovo webhook selezionando Registra un nuovo webhook nell'opzione di menu Registra.
Compare la seguente finestra di dialogo Registrazione WebHook, in cui è possibile configurare l'URL dell'endpoint e le opzioni di autenticazione.
Registrazione mediante l'autenticazione HTTPHeader
Se si seleziona l'autenticazione HttpHeader, la schermata richiede di immettere valori nei campi Chiavi e Valori che verranno passati come parte della richiesta HTTP. In genere, le chiavi e i valori possono includere un token di connessione OAuth o altri formati di autenticazione.
Registrazione mediante l'autenticazione WebhookKey
Se si specifica WebhookKey come metodo di autenticazione, all'URL viene passata una stringa di query con la chiave specificata nel formato ?code=[web hook key]. Questo metodo è utile quando si chiama il servizio Funzioni di Azure perché usa questo parametro di codice per impostazione predefinita per eseguire l'autenticazione.
Registrazione mediante l'autenticazione HTTPQueryString
È possibile passare i parametri della stringa di query specificando HttpQueryString come opzione Autenticazione. Analogamente all'opzione HTTPHeader, questa opzione consente di passare un set di coppie chiave/valore all'API Web. È inoltre possibile passare altri parametri, nonché passare manualmente il parametro "code" previsto dal servizio Funzioni di Azure.
