Create a service endpoint

  • Article
  • 5 minutes to read

Azure DevOps Services | Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018

Service endpoints are a style for Azure DevOps to connect to external systems or services. They're a bundle of properties securely stored by Azure DevOps, which includes simply isn't limited to the following properties:

  • Service name
  • Description
  • Server URL
  • Certificates or tokens
  • User names and passwords

Annotation

Service endpoints are called service connections in TFS 2018 and earlier versions. Pipelines are called build definitions in TFS 2018 and and earlier versions.

Extensions are then able to use the service endpoint to acquire the stored details to do the necessary operations on that service. Follow this guide to create a new Service Bespeak contribution and utilise information technology in your extension.

Chore overview

You tin develop a service endpoint past creating an example extension for Azure DevOps that includes the following items:

  • A custom service endpoint with data sources, which enables a build task or dashboard widget to telephone call a REST endpoint on the service/server divers by the endpoint.
  • A build task, which defines two properties: The service endpoint & a picklist, which has values populated from the REST endpoint information source.

Note

Service endpoints created by users are created at the project level, not the organization level.

The steps involved in completing this task are:

  • 1. Create the extension manifest file
  • 2. Create the build job pipeline, in the task.json file

Note

This tutorial refers to the abode directory for your project as "home".

Create the manifest file: vss-extension.json

The manifest file defines the custom endpoint and links to the task.json manifest for the build task.

In this article, the manifest file creation is separated into the following 3 parts:

  • Create the basic manifest file
  • Add a custom endpoint contribution
  • Add a build task

Create bones manifest file

Create a json file (vss-extension.json, for instance) in the domicile directory of your 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"     }   ] }

Notation

Y'all need to update the publisher belongings. And "BuildTaskFolder" is the path where we'll somewhen place our build task pipeline.

Add the custom endpoint contribution

Add the following contributions array underneath the targets array of the bones manifest content.

Of import

  • Service connection parameters must be fetched by service connection ID.
                              "contributions": [     {       "id": "service-endpoint",       "clarification": "Service endpoint blazon 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": faux,                   "dataType": "cord"                 }               },               {                 "id": "countersign",                 "name": "Countersign",                 "description": "Countersign",                 "inputMode": "passwordbox",                 "isConfidential": true,                 "validation": {                   "isRequired": false,                   "dataType": "cord"                 }               }             ]           }          ],         "helpMarkDown": "<a href=\"url-to-documentation\" target=\"_blank\"><b>Learn More</b></a>"       }     },   ],

If you've successfully added the service contribution, you run into the Fabrikam endpoint when you try to add together a new service endpoint to your arrangement.

Create a service endpoint using the Fabrikam endpoint.

Screenshot of service endpoint set up.

Add the build task contribution

Inside the contributions array from the previous pace, add the following object to the finish.

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

The dataSource endpoint URL gets computed from the URL of the endpoint (or a stock-still URL), and some other values. For this tutorial, this Remainder call returns nothing and is meant to exist replaced by any Balance calls you lot wish to make to your service.

It's possible to use other parameters than the endpoint URL for the REST URL, for example some endpoint backdrop. For case, assuming that we had a property in the endpoint named subscriptionId, the REST URL could apply information technology with the following syntax: $(endpoint.subscription).

Create the build task

The task.json file describes your build task.

Create a task.json file in your BuildTaskFolder directory, if y'all haven't created this binder nonetheless, practise and so at present.

              {   "id": "6557a6d2-4caf-4247-99ea-5131286a8753",   "proper name": "build-chore",   "friendlyName": "Build Task that uses the service endpoint",   "description": "Job 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": "ane",     "Patch": "ane"   },   "minimumAgentVersion": "ane.95.0",   "instanceNameFormat": "Service Endpoint Build Chore $(project)",   "inputs": [     {       "proper name": "FabrikamService",       "blazon": "connectedService:Fabrikam",       "label": "Fabrikam service/server end point",       "defaultValue": "",       "required": true,       "helpMarkDown": "Select the Fabrikam end point to utilise. 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 components

The FabrikamService input object

This field is the kickoff of blazon connectedService:Fabrikam.connectedService expresses that it'due south an endpoint type, and that Fabrikam is the name of the object.

The project input object

This field is 2nd. It's a picklist.

  • This field is populated past a Rest call.
  • The values from the field "project" are taken from the "Projects" REST information source of the custom endpoint.
  • Expressed in the dataSourceBindings array.
    • The target is the name of the build task field to be populated ("project").
    • The endpointId is the name of the build task field containing the custom endpoint type.
    • The REST call is chosen by the dataSourceName.

If y'all've added the Build Task successfully, y'all should now come across the Build Chore when you're adding tasks to a build pipeline.

Service endpoint build task selector image.

One time you've added the Build Task to your pipeline, confirm that information technology can come across the Fabrikam endpoint you created. The projects dropdown in this tutorial is bare since we aren't using a existent service. Once you lot replace Fabrikam with your service, replace the Projects call with your own REST API phone call to use dynamic data inside your build task.

Service endpoint build task setup image.

Hallmark

The authentication scheme in a service endpoint determines the credentials that would be used to connect to the external service. For more data and to see the following hallmark schemes, see the authentication schemes documentation.

  • Basic authentication
  • Token-based authentication
  • Document-based hallmark
  • No authentication

Side by side steps

  • Test and debug extensions
  • Develop a web extension
  • Add a pipeline decorator