Creare un endpoint di servizio

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

Gli endpoint di servizio consentono ad Azure DevOps di connettersi a sistemi o servizi esterni. Si tratta di un bundle di proprietà archiviate in modo sicuro da Azure DevOps, incluse ma non limitate alle proprietà seguenti:

• Nome del servizio
• Descrizione
• URL del server
• Certificati o token
• Nomi utente e password

Le estensioni possono quindi usare l'endpoint di servizio per acquisire i dettagli archiviati per eseguire le operazioni necessarie su tale servizio. Seguire questa guida per creare un nuovo contributo all'endpoint di servizio e usarlo nell'estensione.

Panoramica delle attività

È possibile sviluppare un endpoint di servizio creando un'estensione di esempio per Azure DevOps che include gli elementi seguenti:

• Un endpoint di servizio personalizzato con origini dati, che consente a un widget di compilazione o dashboard di chiamare un endpoint REST nel servizio o nel server definito dall'endpoint.
• Un'attività di compilazione, che definisce due proprietà: l'endpoint di servizio e un elenco di selezione, che contiene valori popolati dall'origine dati dell'endpoint REST.

I passaggi necessari per completare questa attività sono:

• 1. Creare il file manifesto dell'estensione
• 2. Creare la pipeline dell'attività di compilazione nel file task.json

Creare il file manifesto: vss-extension.json

Il file manifesto definisce l'endpoint personalizzato e i collegamenti al manifesto task.json per l'attività di compilazione.

In questo articolo la creazione del file manifesto è suddivisa nelle tre parti seguenti:

• Creare un endpoint di servizio
  • Panoramica delle attività
  • Creare il file manifesto: vss-extension.json
    • Creare un file manifesto di base
    • Aggiungere il contributo dell'endpoint personalizzato
    • Aggiungere il contributo dell'attività di compilazione
  • Crea l'attività di compilazione
    • componentitask.json
  • Autenticazione
  • Passaggi successivi
  • Contenuto correlato

Creare un file manifesto di base

Creare un file JSON (vss-extension.json, ad esempio) nella directory dell'estensione home.

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

Aggiungere il contributo dell'endpoint personalizzato

Aggiungere la matrice seguente contributions sotto la targets matrice del contenuto del manifesto di base.

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

Se il contributo al servizio è stato aggiunto correttamente, viene visualizzato l'endpoint Fabrikam quando si tenta di aggiungere un nuovo endpoint di servizio all'organizzazione.

Creare un endpoint di servizio usando l'endpoint Fabrikam.

Aggiungere la componente dell'attività di build

All'interno della contributions matrice del passaggio precedente aggiungere l'oggetto seguente alla fine.

{
      "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 dell'endpoint di dataSource viene calcolata dall'URL dell'endpoint, da un URL fisso e alcuni altri valori. Per questa esercitazione, questa chiamata REST non restituisce nulla e deve essere sostituita da qualsiasi chiamata REST che si vuole effettuare al servizio.

È possibile usare altri parametri rispetto all'URL dell'endpoint per l'URL REST, ad esempio alcune proprietà dell'endpoint. Ad esempio, supponendo che nell'endpoint sia presente una proprietà denominata subscriptionId, l'URL REST potrebbe usarlo con la sintassi seguente: $(endpoint.subscription).

Creare l'attività di compilazione

Il task.json file descrive l'attività di compilazione.

Creare un task.json file nella BuildTaskFolder directory, se non è ancora stata creata questa cartella, procedere ora.

{
  "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, select '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"
    }
  }
}

componenti di task.json

Oggetto FabrikamService di input

Questo campo è il primo di tipo connectedService:Fabrikam.connectedService esprime che si tratta di un tipo di endpoint e che Fabrikam è il nome dell'oggetto.

Oggetto project di input

Questo campo è secondo. È un elenco di selezione.

• Questo campo viene popolato da una chiamata REST.
• I valori del campo "project" vengono ricavati dall'origine dati REST "Projects" dell'endpoint personalizzato.
• Espresso nella dataSourceBindings matrice.
  • La destinazione è il nome del campo di compilazione da compilare ("progetto").
  • EndpointId è il nome del campo dell'attività di compilazione contenente il tipo di endpoint personalizzato.
  • La chiamata REST viene scelta da dataSourceName.

Se hai aggiunto correttamente l'Attività di build, dovresti ora vedere l'Attività di build quando si aggiungono le attività a una pipeline di build.

Dopo aver aggiunto l'attività di compilazione alla pipeline, verificare che sia possibile visualizzare l'endpoint Fabrikam creato. L'elenco a discesa dei progetti in questa esercitazione è vuoto perché non si usa un servizio reale. Dopo aver sostituito Fabrikam con il tuo servizio, sostituisci la chiamata Projects con la tua chiamata API REST per utilizzare dati dinamici all'interno del tuo compito di build.

Autenticazione

Lo schema di autenticazione in un endpoint di servizio determina le credenziali che verrebbero usate per connettersi al servizio esterno. Per altre informazioni e per visualizzare gli schemi di autenticazione seguenti, vedere la documentazione sugli schemi di autenticazione.

• Autenticazione di base
• Autenticazione basata su token
• Autenticazione basata su certificati
• Nessuna autenticazione

Passaggi successivi

Contenuti correlati

• Testare e debug delle estensioni
• Sviluppare un'estensione Web
• Aggiungere un decoratore della pipeline