Créer un point de terminaison de service

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

Les points de terminaison de services sont utilisés par Azure DevOps pour se connecter à des services ou systèmes externes. Il s’agit d’un ensemble de propriétés stockées en toute sécurité par Azure DevOps, qui inclut, mais n’est pas limité aux propriétés suivantes :

• Nom du service
• Description
• URL du serveur
• Certificats ou jetons
• Noms d’utilisateur et mots de passe

Les extensions peuvent ensuite utiliser le point de terminaison de service pour acquérir les détails stockés pour effectuer les opérations nécessaires sur ce service. Suivez ce guide pour créer une contribution de point de terminaison de service et l’utiliser dans votre extension.

Conseil

Consultez notre documentation la plus récente sur le développement d’extensions à l’aide du Kit de développement logiciel (SDK) d’extension Azure DevOps.

Vue d’ensemble de la tâche

Vous pouvez développer un point de terminaison de service en créant un exemple d’extension pour Azure DevOps qui inclut les éléments suivants :

• Point de terminaison de service personnalisé avec des sources de données, qui permet à une tâche de génération ou à un widget de tableau de bord d’appeler un point de terminaison REST sur le service/serveur défini par le point de terminaison.
• Tâche de génération, qui définit deux propriétés : le point de terminaison de service et une liste de sélections, qui a des valeurs remplies à partir de la source de données du point de terminaison REST.

Remarque

Lorsque vous créez des points de terminaison de service, il s’agit au niveau du projet, et non au niveau de l’organisation.

Les étapes impliquées dans l’exécution de cette tâche sont les suivantes :

• 1. Créer le fichier manifeste d’extension
• 2. Créer le pipeline de tâches de génération, dans le fichier task.json

Remarque

Ce tutoriel fait référence au répertoire de base de votre projet comme « accueil ».

Créez le fichier manifeste : vss-extension.json

Le fichier manifeste définit le point de terminaison personnalisé et les liens vers le manifeste task.json pour la tâche de génération.

Dans cet article, la création du fichier manifeste est séparée dans les trois parties suivantes :

• Créer un point de terminaison de service
  • Vue d’ensemble de la tâche
  • Créez le fichier manifeste : vss-extension.json
    • Créer un fichier manifeste de base
    • Ajouter la contribution de point de terminaison personnalisé
    • Ajouter la contribution de la tâche de génération
  • Créer la tâche de génération
    • composants task.json
  • Authentification
  • Étapes suivantes
  • Articles connexes

Créer un fichier manifeste de base

Créez un fichier json (vss-extension.jsonpar exemple) dans le home répertoire de votre extension.

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

Remarque

Mettez à jour la propriété publisher. Il BuildTaskFolder s’agit du chemin d’accès où nous allons finalement placer notre pipeline de tâches de génération.

Ajouter la contribution de point de terminaison personnalisé

Ajoutez le tableau suivant contributions sous le targets tableau du contenu du manifeste de base.

Important

Les paramètres de connexion de service doivent être récupérés par ID de connexion de service.

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

Si vous avez ajouté la contribution du service, vous voyez le point de terminaison Fabrikam lorsque vous essayez d’ajouter un nouveau point de terminaison de service à votre organisation.

Créez un point de terminaison de service à l’aide du point de terminaison Fabrikam.

Conseil

Vous pouvez ajouter inputDescriptors sans authenticationSchemes. Pour plus d’informations, consultez l’interface InputDescriptor.

Ajouter la contribution de la tâche de génération

À l’intérieur du contributions tableau de l’étape précédente, ajoutez l’objet suivant à la fin.

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

L’URL du point de terminaison dataSource est calculée à partir de l’URL du point de terminaison ou d’une URL fixe, ainsi que d’autres valeurs. Pour ce tutoriel, cet appel REST ne retourne rien et est destiné à être remplacé par tous les appels REST que vous souhaitez effectuer à votre service.

Il est possible d’utiliser d’autres paramètres que l’URL de point de terminaison pour l’URL REST, par exemple certaines propriétés de point de terminaison. Par exemple, en supposant que nous avions une propriété dans le point de terminaison nommé subscriptionId, l’URL REST pouvait l’utiliser avec la syntaxe suivante : $(endpoint.subscription).

Créer la tâche de génération

Le task.json fichier décrit votre tâche de génération.

Remarque

Pour plus d’informations, case activée les articles suivants :

• Référence de tâche de génération pour rechercher le schéma du fichier json de tâche de génération
• Ajouter une extension de tâche de pipelines personnalisée
• Intégrer la tâche de génération

Créez un task.json fichier dans votre BuildTaskFolder répertoire, si vous n’avez pas encore créé ce dossier, faites-le maintenant.

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

composants task.json

Objet FabrikamService d’entrée

Ce champ est le premier de type connectedService :Fabrikam.connectedService exprime qu’il s’agit d’un type de point de terminaison et que Fabrikam est le nom de l’objet.

Objet project d’entrée

Ce champ est deuxième. C’est une liste de choix.

• Ce champ est rempli par un appel REST.
• Les valeurs du champ « projet » sont extraites de la source de données REST « Projects » du point de terminaison personnalisé.
• Exprimé dans le dataSourceBindings tableau.
  • La cible est le nom du champ de tâche de génération à remplir (« projet »).
  • EndpointId est le nom du champ de tâche de génération contenant le type de point de terminaison personnalisé.
  • L’appel REST est choisi par dataSourceName.

Si vous avez ajouté la tâche de génération avec succès, vous devez maintenant voir la tâche de génération lorsque vous ajoutez des tâches à un pipeline de build.

Une fois que vous avez ajouté la tâche de génération à votre pipeline, vérifiez qu’elle peut voir le point de terminaison Fabrikam que vous avez créé. La liste déroulante des projets de ce didacticiel est vide, car nous n’utilisons pas de service réel. Une fois que vous avez remplacé Fabrikam par votre service, remplacez l’appel Projects par votre propre appel d’API REST pour utiliser des données dynamiques dans votre tâche de génération.

Authentification

Le schéma d’authentification dans un point de terminaison de service détermine les informations d’identification qui seraient utilisées pour se connecter au service externe. Pour plus d’informations et pour consulter les schémas d’authentification suivants, consultez la documentation sur les schémas d’authentification.

• Authentification de base
• Authentification basée sur un jeton
• Authentification par certificat
• Aucune authentification

Étapes suivantes

Empaqueter, publier et installer des extensions

Articles connexes

• Tester et déboguer des extensions
• Développer une extension web
• Ajouter un décorateur de pipeline