创建服务终结点

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

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

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

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

提示

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

任务概述

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

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

注意

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

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

• 1.创建扩展清单文件
• 2. 在task.json文件中创建生成任务管道

注意

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

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

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

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

• 创建服务终结点
  • 任务概述
  • 创建清单文件： 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 描述生成任务。

注意

有关详细信息，检查以下文章：

• 生成任务引用 以查找生成任务 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,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组件

FabrikamService输入对象

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

project输入对象

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

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

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

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

身份验证

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

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

后续步骤

打包、发布和安装扩展

相关文章

• 测试和调试扩展
• 开发 Web 扩展
• 添加管道修饰器