Condividi tramite

Creare un endpoint di servizio

  • Articolo

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 servizio
  • Descrizione
  • URL 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.

Suggerimento

Vedere la documentazione più recente sullo sviluppo di estensioni con Azure DevOps Extension SDK.

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.

Nota

Quando si creano endpoint di servizio, si trova a livello di progetto, non a livello di organizzazione.

I passaggi necessari per completare questa attività sono:

Nota

Questa esercitazione fa riferimento alla home directory del progetto come "home".

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 file manifesto di base

Creare un file JSON (vss-extension.jsonad 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"
    }
  ]
}

Nota

Aggiornare la publisher proprietà . BuildTaskFolder è il percorso in cui verrà posizionata la pipeline dell'attività di compilazione.

Aggiungere il contributo dell'endpoint personalizzato

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

Importante

I parametri di connessione del servizio devono essere recuperati in base all'ID connessione del servizio.

  "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.

Screenshot della configurazione dell'endpoint di servizio.

Suggerimento

È possibile aggiungere inputDescriptor senza authenticationSchemes. Per altre informazioni, vedere Interfaccia inputDescriptor.

Aggiungere il contributo dell'attività di compilazione

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 dataSource viene calcolato dall'URL dell'endpoint o da un URL fisso e 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.

Nota

Per altre informazioni, vedere gli articoli seguenti:

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

componenti 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 a discesa.

  • 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 dell'attività di compilazione da popolare ("progetto").
    • EndpointId è il nome del campo dell'attività di compilazione contenente il tipo di endpoint personalizzato.
    • La chiamata REST viene scelta da dataSourceName.

Se l'attività di compilazione è stata aggiunta correttamente, verrà visualizzata l'attività di compilazione quando si aggiungono attività a una pipeline di compilazione.

Immagine del selettore dell'attività di compilazione dell'endpoint di servizio.

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 servizio, sostituire la chiamata Projects con la propria chiamata API REST per usare i dati dinamici all'interno dell'attività di compilazione.

Immagine di configurazione dell'attività di compilazione dell'endpoint di servizio.

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

Creare pacchetti, pubblicare e installare estensioni