Freigeben über

Erstellen eines benutzerdefinierten Consumers für Diensthaken

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Verwenden Sie Dienst-Hooks, um externe Systeme über Ereignisse in Ihrem Azure DevOps-Projekt zu benachrichtigen. Eine benutzerdefinierte Consumererweiterung sendet einen HTTP POST an einen Endpunkt, den Sie konfigurieren, wenn bestimmte Ereignisse auftreten.

Tipp

Wenn Sie eine neue Azure DevOps-Erweiterung starten, probieren Sie diese verwalteten Beispielsammlungen zuerst aus – sie arbeiten mit aktuellen Produktbuilds und behandeln moderne Szenarien (z. B. Hinzufügen von Registerkarten auf Pullanforderungsseiten).

Wenn ein Beispiel in Ihrer Organisation nicht funktioniert, installieren Sie es in einer persönlichen oder Testorganisation und vergleichen Sie die Ziel-IDs und API-Versionen des Erweiterungsmanifests mit den aktuellen Dokumenten. Weitere Informationen und APIs finden Sie unter:

In diesem Artikel wird gezeigt, wie Sie eine Erweiterung erstellen, die einen Beispiel-Consumerdienst implementiert. Der Beispiel-Consumer:

  • Lauscht auf drei Git-Ereignisse: Code gepusht, Pull-Request erstellt und Pull-Request aktualisiert.
  • Sendet einen HTTP POST mit der Ereignisnutzlast an eine konfigurierbare Endpunkt-URL.

Diagramm, das einen Beispiel-Consumerdienst zeigt, der HTTP-Nachrichten für Code-Push- und Pull-Anforderungsereignisse sendet.

Die vollständige Quelle finden Sie im GitHub-Repository der Erweiterung. Alle verfügbaren Ereignistypen finden Sie unter Service Hook-Ereignistypen.

Tipp

Für die neuesten Anleitungen zur Erweiterungsentwicklung, einschließlich Themengestaltung und Migration von VSS.SDK, besuchen Sie das Entwicklerportal des Azure DevOps Extension SDK.

Funktionsweise von Service-Hooks

Service Hooks bestehen aus drei Komponenten:

  • Herausgeber geben Ereignisse aus, z. B. "Code pushed" oder "Pullanforderung erstellt".
  • Abonnements verknüpfen bestimmte Ereignisse und Aktionen.
  • Consumer definieren die auszuführenden Aktionen, z. B. das Senden eines HTTP POST.

Diagramm, das den Dienst-Hook-Fluss zeigt: Herausgeber geben Ereignisse aus, Abonnements stimmen Ereignisse ab und Aktionen werden ausgeführt, wenn ein Ereignis mit einem Abonnement übereinstimmt.

In diesem Artikel implementiert die Erweiterung einen benutzerdefinierten Verbraucher. Wenn ein übereinstimmendes Ereignis auftritt, sendet der Consumer einen HTTP POST mit der Ereignisnutzlast an die im Abonnement konfigurierte Ziel-URL.

Erstellen der Erweiterung

1. Einrichten des Projekts

Erstellen Sie Ihr Erweiterungsprojekt. Anweisungen finden Sie unter Entwickeln einer Weberweiterung.

2. Hinzufügen des Verbraucherbeitrags

Fügen Sie den Verbraucherbeitrag zu Ihrer Manifestdatei hinzu (vss-extension.json). Das folgende Beispiel zeigt ein vollständiges Manifest mit einem Service Hook-Consumer:

{
    "manifestVersion": 1,
    "id": "samples-service-hooks-consumer",
    "version": "0.1.2",
    "name": "Service Hooks Sample",
    "description": "A simple extension that demonstrates how to contribute a consumer service into service hooks.",
    "publisher": "fabrikam",
    "public": false,
    "icons": {
        "default": "images/logo.png"
    },
    "scopes": [],
    "files": [
        {
            "path": "images",
            "addressable": true
        }
    ],
    "content": {
        "details": {
            "path": "readme.md"
        }
    },
    "categories": [
        "Developer samples"
    ],
    "targets": [
        {
            "id": "Microsoft.VisualStudio.Services"
        }
    ],
    "contributions": [
        {
            "id": "consumer",
            "type": "ms.vss-servicehooks.consumer",
            "targets": [
                "ms.vss-servicehooks.consumers"
            ],
            "properties": {
                "id": "consumer",
                "name": "Sample Consumer",
                "description": "Sample consumer service",
                "informationUrl": "https://aka.ms/vsoextensions",
                "inputDescriptors": [
                    {
                        "id": "url",
                        "isRequired": true,
                        "name": "URL",
                        "description": "URL to post event payload to",
                        "inputMode": "textbox"
                    }
                ],
                "actions": [
                    {
                        "id": "performAction",
                        "name": "Perform action",
                        "description": "Posts a standard event payload",
                        "supportedEventTypes": [
                            "git.push",
                            "git.pullrequest.created",
                            "git.pullrequest.updated"
                        ],
                        "publishEvent": {
                            "url": "{{{url}}}",
                            "resourceDetailsToSend": "all",
                            "messagesToSend": "all",
                            "detailedMessagesToSend": "all"
                        }
                    }
                ]
            }
        }
    ]
}

Hinweis

Aktualisieren Sie die publisher Eigenschaft so, dass sie Ihrer Herausgeber-ID entspricht.

Das contributions Array ist der Schlüsselabschnitt. Jeder Beitrag definiert Folgendes:

  • Typ: ms.vss-servicehooks.consumer — registriert einen Verbraucherdienst
  • Ziel: ms.vss-servicehooks.consumers — Sammlung der Verbraucherdienste
  • Eigenschaften: Consumerkonfiguration, einschließlich Eingaben und Aktionen (siehe Eigenschaftsreferenz)

3. Verpacken, Veröffentlichen und Testen

Packen und veröffentlichen Sie die Erweiterung in Ihrer Azure DevOps-Organisation. Erstellen Sie dann ein Service-Hook-Abonnement, das Ihren benutzerdefinierten Consumer verwendet, um dessen Funktionsfähigkeit zu überprüfen.

Eigenschaftsreferenz

Verbrauchereigenschaften

Eigentum BESCHREIBUNG
id Eindeutige ID für den Verbraucherdienst.
name Anzeigename, der angezeigt wird, wenn Benutzer Diensthakenabonnements erstellen.
Beschreibung Beschreibt den Verbraucherdienst.
informationUrl URL, über die Benutzer mehr über die Erweiterung erfahren können.
inputDescriptors Eingaben, die Benutzer beim Erstellen von Abonnements bereitstellen (z. B. einen URL-Endpunkt).
Aktionen Aktionen, die ausgeführt werden sollen, wenn Ereignisse auftreten und welche Ereignistypen jede Aktion auslösen.

Aktionseigenschaften

Jede Aktion im actions Array weist die folgenden Eigenschaften auf:

Eigentum BESCHREIBUNG
id Eindeutige ID (Identifikationsnummer) für die Aktion.
name Anzeigename der Aktion.
Beschreibung Beschreibung dessen, was die Aktion bewirkt.
unterstützteEreignistypen Array von Ereignistyp-IDs, die diese Aktion auslösen. Verfügbare Typen finden Sie unter Service Hook-Ereignistypen.
publishEvent.url Endpunkt-URL, die den HTTP POST empfängt. Verwenden Sie die dreifache Mustache-Syntax ({{{inputId}}}), um die Werte zu ersetzen, die Benutzer beim Erstellen des Abonnements angeben.

Nächster Schritt

Packen, Veröffentlichen und Installieren von Erweiterungen

Verwandte Inhalte

  • Last updated on