Azure DevOps CLI 服务终结点

2025-06-05

Azure DevOps Services

服务连接允许 Azure DevOps 与外部服务（例如 Azure、Bitbucket、Kubernetes、Maven 和 GitHub）通信。 az devops service-endpoint使用此命令，可以创建和管理不同类型的服务连接。可以完成以下任务：

使用配置文件创建服务终结点
更新服务终结点
管理 GitHub 服务终结点和连接
管理 Azure 资源管理器服务终结点和连接
列出为项目定义的服务终结点
获取服务终结点的详细信息

有关详细的命令语法，请参阅 az devops service-endpoint。有关服务终结点的 REST API 的语法，请参阅终结点。

可以使用 Azure CLI 命令获取详细信息、列出、删除和更新服务终结点。请参阅服务终结点或服务连接。

若要使用 Web 门户创建和编辑服务连接，请参阅管理服务连接。

提示

本文中的示例使用服务主体代替基本身份验证，作为一种更安全的身份验证方法。有关详细信息，请参阅在 Azure DevOps 中使用服务主体和托管标识。

使用配置文件创建服务终结点

若要使用配置文件创建服务终结点，请先定义配置文件。配置文件的内容因连接类型而异，例如 Azure 经典、Azure 数据资源管理器、Bitbucket Cloud 或 Chef。

配置文件格式

以下语法显示了配置文件的 JSON 格式。

{
  "data": {},
  "name": "MyNewServiceEndpoint",
  "type": "AzureRM",
  "url": "https://management.azure.com/",
  "authorization": {
    "parameters": {
      "tenantid": "your-tenant-id"
    },
    "scheme": "ManagedServiceIdentity"
  },
  "isShared": false,
  "isReady": true,
  "serviceEndpointProjectReferences": [
    {
      "projectReference": {
        "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
        "name": "TestProject"
      },
      "name": "MyNewServiceEndpoint"
    }
  ]
}

下表对各参数进行了说明：该 type 参数支持创建任何类型的服务终结点。

参数	类型	说明
`name`	字符串	设置终结点的友好名称。
`type`	字符串	设置终结点的类型。
`url`	字符串	设置终结点的 URL。
`authorization`	终端授权	设置用于与终结点通信的授权数据。
`isShared`	布尔	指示服务终结点是否与其他项目共享。
`isReady`	布尔	EndPoint 状态指示器。
`serviceEndpointProjectReferences`	项目参考	设置服务终结点的项目引用。

有关受支持的类型及其所需输入参数的列表，请查看以下 REST API 条目：

https://dev.azure.com/{organization}/_apis/serviceendpoint/types?api-version=6.0-preview.1

有关服务连接类型和参数的说明，请参阅通用服务连接类型。

运行 `create` 命令

使用 az devops service-endpoint create 命令创建服务终结点。

az devops service-endpoint create --service-endpoint-configuration 
                                  [--encoding {ascii, utf-16be, utf-16le, utf-8}]
                                  [--organization]
                                  [--project]

参数

service-endpoint-configuration：必需。 json具有服务终结点配置的配置文件的名称。
编码：可选。输入文件的编码。默认值为 utf-8。接受的值：ascii、utf-16be、utf-16le、utf-8。
组织：Azure DevOps 组织 URL。可以使用配置默认组织 az devops configure --defaults organization=ORG_URL。如果未配置为默认值，则为必需。
project：项目的名称或 ID。可以使用配置默认项目 az devops configure --defaults project=NAME_OR_ID。如果未配置为默认值，则为必需。

示例

以下命令创建引用 ServiceConnectionGeneric.json 文件的服务连接。

az devops service-endpoint create --service-endpoint-configuration ./ServiceConnectionGeneric.json

创建后，该命令会向服务终结点分配一个 Id 。此示例返回以下结果。

{
  "administratorsGroup": null,
  "authorization": {
    "parameters": {
      "serviceprincipalid": "your-service-principal-id",
      "serviceprincipalkey": "your-service-principal-key",
      "tenantid": "your-tenant-id"
    },
    "scheme": "ServicePrincipal"
  },
  "createdBy": {
    "descriptor": "aad.OGYxZTFlODEtMGJiNC03N2ZkLThkYzUtYjE3MTNiNTQ2MjQ4",
    "directoryAlias": null,
    "displayName": "Jamal Hartnett",
    "id": "60c83423-4eb6-4c5e-8395-1e71cb4aef4c",
    "imageUrl": "https://dev.azure.com/fabrikam/_apis/GraphProfile/MemberAvatars/aad.OGYxZTFlODEtMGJiNC03N2ZkLThkYzUtYjE3MTNiNTQ2MjQ4",
    "inactive": null,
    "isAadIdentity": null,
    "isContainer": null,
    "isDeletedInOrigin": null,
    "profileUrl": null,
    "uniqueName": "fabrikamfiber4@hotmail.com",
    "url": "https://spsprodwcus0.vssps.visualstudio.com/A0214b8cc-a36c-4b93-abbf-6348473c2f0a/_apis/Identities/60c83423-4eb6-4c5e-8395-1e71cb4aef4c"
  },
  "data": {},
  "description": null,
  "groupScopeId": null,
  "id": "3b6890ef-54b3-47ec-a907-a5d2f96237da",
  "isReady": true,
  "isShared": false,
  "name": "MyNewServiceEndpoint",
  "operationStatus": null,
  "owner": "library",
  "readersGroup": null,
  "serviceEndpointProjectReferences": [
    {
      "name": "MyNewServiceEndpoint",
      "projectReference": {
        "id": "677da0fb-b067-4f77-b89b-f32c12bb8617",
        "name": null
      }
    }
  ],
  "type": "Generic",
  "url": "https://myserver"
}

创建 GitHub 服务终结点

若要创建 GitHub 服务终结点，请使用 az devops service-endpoint github create 命令：

az devops service-endpoint github create --github-url
                                         --name 
                                         [--organization]
                                         [--project]

在交互模式下， az devops service-endpoint github create 命令提示符会提示你输入 GitHub PAT 令牌。出于自动化目的，请使用 AZURE_DEVOPS_EXT_GITHUB_PAT 环境变量设置 GitHub PAT 令牌。有关详细信息，请参阅使用个人访问令牌登录。

创建 Azure 资源管理器服务终结点

若要创建 Azure 资源管理器服务终结点，请使用 az devops service-endpoint azurerm create 命令。

az devops service-endpoint azurerm create --azure-rm-service-principal-id
                                          --azure-rm-subscription-id
                                          --azure-rm-subscription-name
                                          --azure-rm-tenant-id
                                          --name
                                          [--azure-rm-service-principal-certificate-path] 
                                          [--organization]
                                          [--project]

使用客户端密码

在交互模式下， az devops service-endpoint azurerm create 命令提示符会提示你输入服务主体机密。出于自动化目的，请使用 AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY 环境变量设置服务主体机密。

export AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY=<your_secret_here>

$env:AZURE_DEVOPS_EXT_AZURE_RM_SERVICE_PRINCIPAL_KEY=<your_secret_here>

使用客户端证书

如果 Microsoft Entra 应用程序使用证书进行身份验证，请为证书创建 .pem 文件。使用 --azure-rm-service-principal-certificate-path 参数将路径传递给 .pem 文件。

可以使用 OpenSSL 创建 .pem 文件：

openssl pkcs12 -in file.pfx -out file.pem -nodes -secret pass:<secret_here>

通过