创建服务终结点

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

通过服务终结点,Azure DevOps 可以连接到外部系统或服务。 它们是 Azure DevOps 安全地存储的属性捆绑包,其中包括但不限于以下属性:

  • 服务名称
  • 描述
  • 服务器 URL
  • 证书或令牌
  • 用户名和密码

然后,扩展可以使用服务终结点获取存储的详细信息,以对该服务执行必要的操作。 按照本指南创建新的服务终结点贡献,并将其用于扩展。

提示

查看有关使用 Azure DevOps 扩展 SDK 进行扩展开发的最新文档。

任务概述

可以通过为 Azure DevOps 创建包含以下项的示例扩展来开发服务终结点:

  • 具有数据源的自定义服务终结点,使生成任务或仪表板小组件能够在终结点定义的服务/服务器上调用 REST 终结点。
  • 一个生成任务,该任务定义两个属性:服务终结点和选取列表,其中包含从 REST 终结点数据源填充的值。

注意

创建服务终结点时,它位于项目级别,而不是组织级别。

完成此任务所涉及的步骤包括:

注意

本教程将项目的主目录称为“home”。

创建清单文件: vss-extension.json

清单 文件 定义自定义终结点,并链接到生成任务的task.json清单。

在本文中,清单文件创建分为以下三个部分:

创建基本清单文件

在扩展的目录中创建 json 文件(vss-extension.json例如 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"
    }
  ]
}

注意

更新 publisher 属性。 这是 BuildTaskFolder 最终放置生成任务管道的路径。

添加自定义终结点贡献

在基本清单内容的数组下面targets添加以下contributions数组。

重要

服务连接参数必须由服务连接 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>"
      }
    },
  ],

如果已成功添加服务贡献,则尝试向组织添加新服务终结点时,会看到 Fabrikam 终结点。

使用 Fabrikam 终结点创建服务终结点。

设置服务终结点的屏幕截图。

提示

无需 authenticationSchemes 即可添加 inputDescriptors。 有关详细信息,请参阅 InputDescriptor 接口

添加生成任务贡献

在上一步的数组中 contributions ,将以下对象添加到末尾。

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

DataSource 终结点 URL 从终结点的 URL 或固定 URL 以及一些其他值进行计算。 在本教程中,此 REST 调用将不返回任何内容,并且将替换为你希望对服务进行的任何 REST 调用。

可以使用 REST URL 的终结点 URL 以外的其他参数,例如某些终结点属性。 例如,假设我们在名为 subscriptionId 的终结点中具有属性,REST URL 可以使用以下语法:$(endpoint.subscription)。

创建生成任务

该文件 task.json 描述生成任务。

注意

有关详细信息,检查以下文章:

如果尚未创建此文件夹,请在目录中创建一个 task.json 文件 BuildTaskFolder ,现在请执行此操作。

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

task.json组件

FabrikamService输入对象

此字段是 connectedService:Fabrikam.connectedService 的第一个类型,表示它是终结点类型,Fabrikam 是对象的名称。

project输入对象

此字段为第二个字段。 这是一个选取列表。

  • 此字段由 REST 调用填充。
  • 字段“project”中的值取自自定义终结点的“Projects”REST 数据源。
  • dataSourceBindings 数组表示。
    • 目标是要填充的生成任务域的名称(“项目”)。
    • endpointId 是包含自定义终结点类型的生成任务字段的名称。
    • REST 调用由 dataSourceName 选择。

如果已成功添加生成任务,则现在应在将任务添加到生成管道时看到生成任务。

服务终结点生成任务选择器映像。

将生成任务添加到管道后,确认它可以看到创建的 Fabrikam 终结点。 本教程中的项目下拉列表为空,因为我们未使用实际服务。 将 Fabrikam 替换为服务后,请将 Projects 调用替换为自己的 REST API 调用,以在生成任务中使用动态数据。

服务终结点生成任务设置映像。

身份验证

服务终结点中的身份验证方案确定用于连接到外部服务的凭据。 有关详细信息并查看以下身份验证方案,请参阅 身份验证方案文档

  • 基本身份验证
  • 基于令牌的身份验证
  • 基于证书的身份验证
  • 无身份验证

后续步骤