Een service-eindpunt maken

  • Artikel

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

Service-eindpunten zijn een manier voor Azure DevOps om verbinding te maken met externe systemen of services. Ze zijn een bundel met eigenschappen die veilig zijn opgeslagen door Azure DevOps, waaronder de volgende eigenschappen niet zijn beperkt:

  • Servicenaam
  • Beschrijving
  • Server-URL
  • Certificaten of tokens
  • Gebruikersnamen en wachtwoorden

Extensies kunnen vervolgens het service-eindpunt gebruiken om de opgeslagen gegevens te verkrijgen om de benodigde bewerkingen voor die service uit te voeren. Volg deze handleiding om een nieuwe bijdrage aan het service-eindpunt te maken en deze te gebruiken in uw extensie.

Tip

Bekijk onze nieuwste documentatie over uitbreidingsontwikkeling met behulp van de Azure DevOps Extension SDK.

Overzicht van taken

U kunt een service-eindpunt ontwikkelen door een voorbeeldextensie te maken voor Azure DevOps die de volgende items bevat:

  • Een aangepast service-eindpunt met gegevensbronnen, waarmee een buildtaak of dashboardwidget een REST-eindpunt kan aanroepen op de service/server die door het eindpunt is gedefinieerd.
  • Een build-taak, die twee eigenschappen definieert: het service-eindpunt en een selectielijst met waarden die zijn ingevuld uit de GEGEVENSbron van het REST-eindpunt.

Notitie

Wanneer u een service-eindpunt maakt, is dit op projectniveau, niet op organisatieniveau.

De stappen voor het voltooien van deze taak zijn:

Notitie

Deze zelfstudie verwijst naar de basismap voor uw project als 'home'.

Maak het manifestbestand: vss-extension.json

Het manifestbestand definieert het aangepaste eindpunt en koppelingen naar het task.json manifest voor de build-taak.

In dit artikel wordt het maken van het manifestbestand onderverdeeld in de volgende drie onderdelen:

Basismanifestbestand maken

Maak een json-bestand (vss-extension.jsonbijvoorbeeld) in de home map van uw extensie.

{
"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"
    }
  ]
}

Notitie

Werk de publisher eigenschap bij. Het BuildTaskFolder is het pad waar we uiteindelijk onze build-taakpijplijn plaatsen.

De bijdrage van het aangepaste eindpunt toevoegen

Voeg de volgende contributions matrix toe onder de targets matrix van de basismanifestinhoud.

Belangrijk

Serviceverbindingsparameters moeten worden opgehaald op basis van serviceverbindings-id.

  "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>"
      }
    },
  ],

Als u de servicebijdrage hebt toegevoegd, ziet u het Fabrikam-eindpunt wanneer u probeert een nieuw service-eindpunt toe te voegen aan uw organisatie.

Maak een service-eindpunt met behulp van het Fabrikam-eindpunt.

Schermopname van het instellen van het service-eindpunt.

Tip

U kunt inputDescriptors toevoegen zonder authenticationSchemes. Zie de InputDescriptor-interface voor meer informatie.

De bijdrage van de build-taak toevoegen

Voeg in de contributions matrix uit de vorige stap het volgende object toe aan het einde.

{
      "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"
      }
    }

De dataSource-eindpunt-URL wordt berekend op basis van de URL van het eindpunt of een vaste URL en enkele andere waarden. Voor deze zelfstudie retourneert deze REST-aanroep niets en is bedoeld om te worden vervangen door REST-aanroepen die u naar uw service wilt verzenden.

Het is mogelijk om andere parameters te gebruiken dan de eindpunt-URL voor de REST-URL, bijvoorbeeld enkele eindpunteigenschappen. Als we bijvoorbeeld een eigenschap hadden in het eindpunt subscriptionId, kan de REST-URL deze gebruiken met de volgende syntaxis: $(endpoint.subscription).

De build-taak maken

In task.json het bestand wordt uw build-taak beschreven.

Notitie

Raadpleeg de volgende artikelen voor meer informatie:

Maak een task.json bestand in uw BuildTaskFolder map als u deze map nog niet hebt gemaakt, doe dit nu.

{
  "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 onderdelen

Het FabrikamService invoerobject

Dit veld is de eerste van het type connectedService:Fabrikam.connectedService geeft aan dat het een eindpunttype is en dat Fabrikam de naam van het object is.

Het project invoerobject

Dit veld is tweede. Het is een selectielijst.

  • Dit veld wordt ingevuld door een REST-aanroep.
  • De waarden uit het veld 'project' zijn afkomstig uit de REST-gegevensbron Projecten van het aangepaste eindpunt.
  • Uitgedrukt in de dataSourceBindings matrix.
    • Het doel is de naam van het build-taakveld dat moet worden ingevuld ('project').
    • De endpointId is de naam van het build-taakveld met het aangepaste eindpunttype.
    • De REST-aanroep wordt gekozen door de dataSourceName.

Als u de buildtaak hebt toegevoegd, ziet u nu de buildtaak wanneer u taken toevoegt aan een build-pijplijn.

Afbeelding van taakkiezer voor het maken van service-eindpunten.

Nadat u de buildtaak aan uw pijplijn hebt toegevoegd, controleert u of het Fabrikam-eindpunt dat u hebt gemaakt, kan zien. De vervolgkeuzelijst projecten in deze zelfstudie is leeg omdat we geen echte service gebruiken. Nadat u Fabrikam door uw service hebt vervangen, vervangt u de aanroep Projecten door uw eigen REST API-aanroep om dynamische gegevens in uw build-taak te gebruiken.

Installatiekopieën voor het maken van een service-eindpunttaak.

Verificatie

Het verificatieschema in een service-eindpunt bepaalt de referenties die worden gebruikt om verbinding te maken met de externe service. Zie de documentatie voor verificatieschema's voor meer informatie en voor meer informatie over de volgende verificatieschema's.

  • Basisverificatie
  • Verificatie op basis van tokens
  • Verificatie op basis van certificaat
  • Geen verificatie

Volgende stappen

Extensies verpakken, publiceren en installeren