Erstellen eines Dienstendpunkts

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

Dienstendpunkte sind eine Möglichkeit für Azure DevOps, sich mit externen Systemen oder Diensten zu verbinden. Sie sind ein Paket von Eigenschaften, die sicher von Azure DevOps gespeichert werden, die jedoch nicht auf die folgenden Eigenschaften beschränkt sind:

• Dienstname
• Beschreibung
• Server-URL
• Zertifikate oder Token
• Benutzernamen und Kennwörter

Erweiterungen können dann den Dienstendpunkt verwenden, um die gespeicherten Details abzurufen, um die erforderlichen Vorgänge für diesen Dienst auszuführen. Befolgen Sie diesen Leitfaden, um einen neuen Beitrag zum Dienstendpunkt zu erstellen und ihn in Ihrer Erweiterung zu verwenden.

Tipp

Sehen Sie sich unsere neueste Dokumentation zur Erweiterungsentwicklung mithilfe des Azure DevOps-Erweiterungs-SDK an.

Aufgabenübersicht

Sie können einen Dienstendpunkt entwickeln, indem Sie eine Beispielerweiterung für Azure DevOps erstellen, die die folgenden Elemente enthält:

• Ein benutzerdefinierter Dienstendpunkt mit Datenquellen, mit dem ein Buildaufgaben- oder Dashboard-Widget einen REST-Endpunkt auf dem vom Endpunkt definierten Dienst/Server aufrufen kann.
• Eine Buildaufgabe, die zwei Eigenschaften definiert: Der Dienstendpunkt und eine Auswahlliste, die Werte aus der REST-Endpunktdatenquelle aufgefüllt hat.

Hinweis

Wenn Sie einen Dienstendpunkt erstellen, befindet es sich auf Projektebene, nicht auf Organisationsebene.

Die Schritte zum Ausführen dieser Aufgabe sind:

• 1. Erstellen der Erweiterungsmanifestdatei
• 2. Erstellen der Buildaufgabenpipeline in der datei task.json

Hinweis

Dieses Lernprogramm bezieht sich auf das Startverzeichnis für Ihr Projekt als "Start".

Erstellen Sie die Manifestdatei: vss-extension.json

Die Manifestdatei definiert den benutzerdefinierten Endpunkt und links zum task.json Manifest für die Buildaufgabe.

In diesem Artikel wird die Manifestdateierstellung in die folgenden drei Teile unterteilt:

• Erstellen eines Dienstendpunkts
  • Aufgabenübersicht
  • Erstellen Sie die Manifestdatei: vss-extension.json
    • Erstellen einer einfachen Manifestdatei
    • Hinzufügen des benutzerdefinierten Endpunktbeitrags
    • Hinzufügen des Beitrags zur Buildaufgabe
  • Erstellen der Buildaufgabe
    • task.json-Komponenten
  • Authentifizierung
  • Nächste Schritte
  • Verwandte Artikel

Erstellen einer einfachen Manifestdatei

Erstellen Sie eine JSON-Datei (vss-extension.jsonz. B. im home Verzeichnis Ihrer Erweiterung).

{
"manifestVersion": 1,
  "id": "service-endpoint-tutorial",
  "version": "0.1.1",
  "name": "Sample extension that leverages a service endpoint",
  "description": "A sample Azure DevOps extension which shows how to create a custom endpoint and dynamic build task parameters taking value from a REST API.",
  "publisher": "francistotten",
  "targets": [
    {
      "id": "Microsoft.VisualStudio.Services"
    }
  ],  
  "files": [
    {
      "path": "BuildTaskFolder"
    }
  ]
}

Hinweis

Aktualisieren Sie die publisher-Eigenschaft. Dies BuildTaskFolder ist der Pfad, in dem wir schließlich unsere Buildaufgabenpipeline platzieren werden.

Hinzufügen des benutzerdefinierten Endpunktbeitrags

Fügen Sie das folgende contributions Array unterhalb des targets Arrays des grundlegenden Manifestinhalts hinzu.

Wichtig

Dienstverbindungsparameter müssen von der Dienstverbindungs-ID abgerufen werden.

  "contributions": [
    {
      "id": "service-endpoint",
      "description": "Service endpoint type for Fabrikam connections",
      "type": "ms.vss-endpoint.service-endpoint-type",
      "targets": [ "ms.vss-endpoint.endpoint-types" ],
      "properties": {
        "name": "fabrikam",
        "displayName": "Fabrikam server connection",
        "url": {
          "displayName": "Server Url",
          "helpText": "Url for the Fabrikam server to connect to."
        },
        "dataSources": [
          {
            "name": "Fabrikam Projects",
            "endpointUrl": "{{endpoint.url}}api/projects/index",
            "resultSelector": "jsonpath:$[*].nm"
          }

        ],
        "authenticationSchemes": [
          {
            "type": "ms.vss-endpoint.endpoint-auth-scheme-token"
          },
          {
            "type": "ms.vss-endpoint.endpoint-auth-scheme-basic",
            "inputDescriptors": [
              {
                "id": "username",
                "name": "Username",
                "description": "Username",
                "inputMode": "textbox",
                "validation": {
                  "isRequired": false,
                  "dataType": "string"
                }
              },
              {
                "id": "password",
                "name": "Password",
                "description": "Password",
                "inputMode": "passwordbox",
                "isConfidential": true,
                "validation": {
                  "isRequired": false,
                  "dataType": "string"
                }
              }
            ]
          }

        ],
        "helpMarkDown": "<a href=\"url-to-documentation\" target=\"_blank\"><b>Learn More</b></a>"
      }
    },
  ],

Wenn Sie den Dienstbeitrag erfolgreich hinzugefügt haben, wird der Fabrikam-Endpunkt angezeigt, wenn Sie versuchen, Ihrer Organisation einen neuen Dienstendpunkt hinzuzufügen.

Erstellen Sie einen Dienstendpunkt mithilfe des Fabrikam-Endpunkts.

Tipp

Sie können inputDescriptors ohne authenticationSchemes hinzufügen. Weitere Informationen finden Sie unter InputDescriptor-Schnittstelle.

Hinzufügen des Beitrags zur Buildaufgabe

Fügen Sie innerhalb des contributions Arrays aus dem vorherigen Schritt das folgende Objekt am Ende hinzu.

{
      "id": "build-task",
      "description": "Task with a dynamic property getting data from an endpoint REST data source",
      "type": "ms.vss-distributed-task.task",
      "targets": [ "ms.vss-distributed-task.tasks" ],
      "properties": {
        "name": "BuildTaskFolder"
      }
    }

Die dataSource-Endpunkt-URL wird von der URL des Endpunkts oder einer festen URL und einigen anderen Werten berechnet. In diesem Lernprogramm gibt dieser REST-Aufruf nichts zurück und soll durch alle REST-Aufrufe ersetzt werden, die Sie an Ihren Dienst senden möchten.

Es ist möglich, andere Parameter als die Endpunkt-URL für die REST-URL zu verwenden, z. B. einige Endpunkteigenschaften. Angenommen, wir hatten eine Eigenschaft im Endpunkt namens subscriptionId, die REST-URL könnte sie mit der folgenden Syntax verwenden: $(endpoint.subscription).

Erstellen der Buildaufgabe

Die task.json Datei beschreibt Ihre Buildaufgabe.

Hinweis

Weitere Informationen finden Sie in den folgenden Artikeln:

• Buildaufgabenreferenz zum Suchen des Schemas für die JSON-Datei der Buildaufgabe
• Hinzufügen einer aufgabenerweiterung für benutzerdefinierte Pipelines
• Buildaufgabe integrieren

Erstellen Sie eine task.json Datei in Ihrem BuildTaskFolder Verzeichnis, wenn Sie diesen Ordner noch nicht erstellt haben, führen Sie dies jetzt aus.

{
  "id": "6557a6d2-4caf-4247-99ea-5131286a8753",
  "name": "build-task",
  "friendlyName": "Build Task that uses the service endpoint",
  "description": "Task with a dynamic property getting data from an endpoint REST data source",
  "author": "francistotten",
  "helpMarkDown": "Replace with Markdown to show in help",
  "category": "Build",
  "visibility": [
    "Build",
    "Release"
  ],
  "demands": [],
  "version": {
    "Major": "0",
    "Minor": "1",
    "Patch": "1"
  },
  "minimumAgentVersion": "1.95.0",
  "instanceNameFormat": "Service Endpoint Build Task $(project)",
  "inputs": [
    {
      "name": "FabrikamService",
      "type": "connectedService:Fabrikam",
      "label": "Fabrikam service/server end point",
      "defaultValue": "",
      "required": true,
      "helpMarkDown": "Select the Fabrikam end point to use. If needed,selecton 'manage', and add a new service endpoint of type 'Fabrikam server connection'"
    },
    {
      "name": "project",
      "type": "pickList",
      "label": "Fabrikam Project",
      "required": true,
      "helpMarkDown": "Select the name of the Fabrikam Project to analyze.",
      "properties": {
        "EditableOptions": "True"
      }
    }
  ],
  "dataSourceBindings": [
    {
      "target": "project",
      "endpointId": "$(FabrikamService)",
      "dataSourceName": "Fabrikam Projects"
    }
  ],
  "execution": {
    "Node": {
      "target": "sample.js",
      "argumentFormat": ""
    },
    "PowerShell3": {
      "target": "sample.ps1"
    }
  }
}

task.json-Komponenten

Das FabrikamService Eingabeobjekt

Dieses Feld ist der erste Typ vom Typ connectedService:Fabrikam.connectedService drückt aus, dass es sich um einen Endpunkttyp handelt, und dass Fabrikam der Name des Objekts ist.

Das project Eingabeobjekt

Dieses Feld ist zweitens. Es ist eine Auswahlliste.

• Dieses Feld wird von einem REST-Aufruf aufgefüllt.
• Die Werte aus dem Feld "Projekt" stammen aus der REST-Datenquelle des benutzerdefinierten Endpunkts.
• Ausgedrückt in der dataSourceBindings Matrix.
  • Das Ziel ist der Name des Zufüllvorgangsfelds ("Projekt").
  • Die endpointId ist der Name des Buildaufgabenfelds, das den benutzerdefinierten Endpunkttyp enthält.
  • Der REST-Aufruf wird vom dataSourceName ausgewählt.

Wenn Sie die Buildaufgabe erfolgreich hinzugefügt haben, sollten Sie nun die Buildaufgabe sehen, wenn Sie einer Buildpipeline Aufgaben hinzufügen.

Nachdem Sie der Pipeline die Buildaufgabe hinzugefügt haben, vergewissern Sie sich, dass er den von Ihnen erstellten Fabrikam-Endpunkt sehen kann. Die Dropdownliste "Projekte" in diesem Lernprogramm ist leer, da wir keinen echten Dienst verwenden. Nachdem Sie Fabrikam durch Ihren Dienst ersetzt haben, ersetzen Sie den Projects-Aufruf durch Ihren eigenen REST-API-Aufruf, um dynamische Daten in Ihrer Buildaufgabe zu verwenden.

Authentifizierung

Das Authentifizierungsschema in einem Dienstendpunkt bestimmt die Anmeldeinformationen, die zum Herstellen einer Verbindung mit dem externen Dienst verwendet werden. Weitere Informationen und die folgenden Authentifizierungsschemas finden Sie in der Dokumentation zu Authentifizierungsschemas.

• Standardauthentifizierung
• Tokenbasierte Authentifizierung
• Zertifikatbasierte Authentifizierung
• Keine Authentifizierung

Nächste Schritte

Packen, Veröffentlichen und Installieren von Erweiterungen

Verwandte Artikel

• Testen und Debuggen von Erweiterungen
• Entwickeln einer Weberweiterung
• Hinzufügen eines Pipelinedekorors