在扩展和集成中使用 URL

Azure DevOps Services

随着 Azure DevOps 的推出，组织资源和 API 现在可通过以下任一 URL 进行访问：

• https://dev.azure.com/{organization} (新)
• https://{organization}.visualstudio.com (旧版)

无论组织创建时间如何，用户、工具和集成都可以使用任一 URL 与组织级 REST API 交互。 作为与 Azure DevOps 交互的扩展、集成或工具的开发人员，了解如何在调用 REST API 时最好地使用提供给代码的 URL 并形成 URL。

有关详细信息，请参阅 REST API 参考。

组织主要 URL

每个组织都有一个指定的 主 URL，该 URL 是新窗体或旧窗体。 Azure DevOps 使用主 URL 来构造在某些情况下的 URL， (更多详细信息，请参阅) 。 组织的默认主 URL 由创建组织的时间确定，但可由管理员更改：

组织创建时间	默认主 URL
在 2018 年 9 月 10 日或之后	新建
2018/9/10 之前	旧的

如何使用主要 URL

主 URL 是 Azure DevOps 在后台作业和其他自动化方案中构造的所有 URL 的基 URL。 请参阅以下示例。

• 通过环境变量（如) ） SYSTEM_TEAMFOUNDATIONCOLLECTIONURI (提供给 Azure Pipelines 任务的 URL
• 服务中包含的 URL 会挂钩事件有效负载 (，如) 中的 resourceContainers URL
• 电子邮件、Slack、Microsoft Teams 和类似通知中的 URL

例如，以下任务代码片段显示提供给任务的组织 URL：

$orgUrl = $env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI
Write-Host $orgUrl

如果在主要 URL 为新 URL 窗体的组织上执行此任务，则输出为 https://dev.azure.com/{organization}。 在主要 URL 为旧 URL 窗体的组织中执行的相同任务输出 https://{organization}.visualstudio.com。

因此，从服务挂钩接收事件的 Azure Pipelines 任务和服务处理这两种 URL 形式非常重要。

REST API 中返回的 URL

无论组织的主要 URL 如何，在响应 REST API 调用时返回的 URL 都使用与请求 URL 相同的基 URL。 此函数可确保使用旧版 URL 调用 REST API 的客户端继续以相同的 (旧) 形式返回 URL。 例如，当使用旧 URL 调用项目 REST API 时，响应中的 URL 使用旧格式：

请求

GET https://Fabrikam.visualstudio.com/_apis/projects/MyProject

响应

{
  "id": "ef4de40d-3d96-4b80-a320-cfafe038ae57",
  "name": "MyProject",
  "url": "https://Fabrikam.visualstudio.com/_apis/projects/MyProject"
}

使用新 URL 调用同一 API (https://dev.azure.com/Fabrikam/_apis/projects/MyProject) 会导致以新 URL 形式返回 URL。

最佳实践

若要确保扩展、工具或集成能够适应组织 URL 表单的更改，以及将来对 REST API 的位置 (域) 的更改，请执行以下操作：

1. 假设组织 URL 的形式可能会随时间而改变。
2. 避免分析 URL 以构造另一个 URL。
3. 不要假设特定的 REST API 始终驻留在同一域中。
4. 避免在服务中存储 URL。
5. 如果可能，请将 Microsoft 提供的 .NET、TypeScript (Web) 、 Node.js和 Python 客户端库与 Azure DevOps 配合使用。

如何获取组织的 URL

只需使用组织的名称或 ID，即可使用全局资源区域 REST API (https://dev.azure.com/_apis/resourceAreas) 获取其基 URL。 此 API 不需要身份验证。 它还提供有关组织的位置 (URL) 的信息，以及 REST API 的基 URL，这些 API 可以位于不同域中。

资源区域是一组相关的 REST API 资源和终结点。 每个资源区域都有一个已知的标识符， (请参阅下表) 。 每个资源区域都有一个特定于组织的基 URL，可用于形成该资源区域中 API 的 URL。 例如，Fabrikam 的“生成”REST API 的基 URL 可能是 https://dev.azure.com/Fabrikam，但“发布管理”REST API 的基 URL 可能是 https://vsrm.dev.azure.com/Fabrikam。

注意

资源区域 REST API 根据组织的指定主 URL 返回组织的 URL。

使用组织名称

有几种方法可以使用组织的名称获取基 URL。

HTTP

请求

将 替换为 {organizationName} 组织的名称，例如“Fabrikam”。 79134C72-4A58-4B42-976C-04E7115F32BF 是“核心”资源区域的 ID，“项目”等重要资源所在的位置。

GET https://dev.azure.com/_apis/resourceAreas/79134C72-4A58-4B42-976C-04E7115F32BF
      ?accountName={organizationName}&api-version=5.0-preview.1

响应

{
    "id": "79134C72-4A58-4B42-976C-04E7115F32BF",
    "name": "Core",
    "locationUrl": "https://dev.azure.com/Fabrikam"
}

反映 locationUrl 组织的基 URL。

C# (客户端库)

Microsoft 提供的 .NET 客户端库 (Microsoft.VisualStudio.Services.Client) 提供了一个帮助程序类，用于调用资源区域 REST API 并返回组织的基 URL。

注意

类 VssConnectionHelper 在客户端库的版本 16.139.0-preview 和更高版本中可用。

using System;
using System.Net.Http;
using System.Threading.Tasks;
using Microsoft.VisualStudio.Services.Common;
using Microsoft.VisualStudio.Services.WebApi;

public async Task MyMethod()
{
    string organizationName = ...;
    VssCredentials credentials = ...;

    Uri organizationUrl = await VssConnectionHelper.GetOrganizationUrlAsync(organizationName);
    
    VssConnection connection = new VssConnection(organizationUrl, credentials);
    
    // get a client using connection.GetClient<T>() and do something
}

C# (泛型)

using System;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json.Linq;

static readonly HttpClient s_client = new HttpClient();
static readonly string s_locationServiceUrl = "https://dev.azure.com";
static readonly Guid s_defaultResourceAreaId = Guid.Parse("79134C72-4A58-4B42-976C-04E7115F32BF");

public async Task<Uri> GetOrganizationUrl(string organizationName)
{
    string requestUrl = $"{s_locationServiceUrl}/_apis/resourceAreas/{s_defaultResourceAreaId}?accountName={organizationName}&api-version=5.0-preview.1";

    HttpResponseMessage response = await s_client.GetAsync(requestUrl);

    if (response.StatusCode == HttpStatusCode.OK)
    {
        var resourceArea = await response.Content.ReadAsAsync<JObject>();

        if (resourceArea != null)
        {
            return new Uri(resourceArea["locationUrl"].ToString());
        }
    }
    
    return null;
}

Node.js（通用）

const request = require('request');

let getOrgUrl = function(orgName, callback) {
    let resourceAreaUrl = 'https://dev.azure.com/_apis/resourceAreas/79134C72-4A58-4B42-976C-04E7115F32BF?' + 
      'accountName=' + orgName +
      '&api-version=5.0-preview.1';
    
    request(resourceAreaUrl, { json: true }, (err, res, body) => {
        if (err) { 
            callback(err);   
        } else {
            callback(null, body.locationUrl);
        }
    });
};

getOrgUrl('fabrikam', (err, url) => {
    console.log(url);
});

使用组织的 ID

若要使用组织的 GUID 标识符获取 URL，请使用 hostId 前面示例中的查询参数 (而不是 accountName) 。 例如：

GET https://dev.azure.com/_apis/resourceAreas/79134C72-4A58-4B42-976C-04E7115F32BF?hostId={organizationId}&api-version=5.0-preview.1

如何获取 REST API 的基 URL

从组织的 URL 开始，可以使用资源区域 REST API 查找需要调用的任何 REST API 的正确基 URL。 此过程可确保代码可复原到将来 REST API 更改的位置 (域) ，并避免潜在的脆弱逻辑。

注意

如果使用 Microsoft 提供的 .NET、TypeScript (Web) 、Node.js 或 Python 客户端库，则会为你处理 URL 查找。 例如，在 .NET 中，构造 VssConnection 并调用 GetClient<T>时，返回的客户端正确绑定到此客户端调用的 REST API 的正确基 URL。

如果未使用 Microsoft 提供的客户端库：

1. 使用下表查找需要调用的 REST API 的资源区域 ID。 资源区域名称通常显示在 REST API 路由的后面 /_apis/ 。 例如， /_apis/release/definitions REST API 属于 release 资源区域，其 ID efc2f575-36ef-48e9-b672-0c6fb4a48ac5为 。

2. ) 调用组织级别的资源区域 REST API ({organizationUrl}/_apis/resourceAreas/{resourceAreaId}?api-version=5.0-preview.1 ，并传递资源区域 ID。 例如：

   GET https://dev.azure.com/Fabrikam/_apis/resourceAreas/efc2f575-36ef-48e9-b672-0c6fb4a48ac5?api-version=5.0-preview.1
   

3. locationUrl使用 JSON 响应中的 字段作为为此区域调用其他 REST API 的基 URL。 在此示例中，Release Management REST API 的基 URL 为 https://vsrm.dev.azure.com/Fabrikam。

与前面所述的全局资源区域 REST API 一样，无需凭据即可调用组织级别的资源区域 REST API。

示例：调用 Azure Pipelines 的管道任务发布 REST API

在此示例中，生成任务需要调用 Azure Pipelines 发布 REST API。 它通过使用环境变量) 和资源区域 REST API 中提供的组织 URL (为此 REST API 调用形成正确的基 URL。

注意

资源区域 ID 是固定的，可以安全地嵌入任务和其他逻辑中。

$orgUrl = $env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI
$releaseManagementAreaId = "efc2f575-36ef-48e9-b672-0c6fb4a48ac5"

# Build the URL for calling the org-level Resource Areas REST API for the RM APIs
$orgResourceAreasUrl = [string]::Format("{0}/_apis/resourceAreas/{1}?api-preview=5.0-preview.1", $orgUrl, $releaseManagementAreaId)

# Do a GET on this URL (this returns an object with a "locationUrl" field)
$results = Invoke-RestMethod -Uri $orgResourceAreasUrl

# The "locationUrl" field reflects the correct base URL for RM REST API calls
$rmUrl = $results.locationUrl

# Construct the URL to the release definitions REST API
$releaseDefinitionsUrl = [string]::Format("{0}/_apis/release/definitions?api-preview=5.0-preview.1", $rmUrl)

资源区域 ID (参考)

此表显示了常见资源区域的 ID。 有关如何使用此表的详细信息，请参阅上一部分。

注意

资源区域 ID 是固定的，在 Azure DevOps Services 的所有组织中都是一致的。

资源区域 ID	名称
0d55247a-1c47-4462-9b1f-5e2125590ee6	account
5d6898bb-45ec-463f-95f9-54d49c71752e	build
79bea8f8-c898-4965-8c51-8bbc3966faa8	collection
79134c72-4a58-4b42-976c-04e7115f32bf	core
31c84e0a-3ece-48fd-a29d-100849af99ba	仪表板
a0848fa1-3593-4aec-949c-694c73f4c4ce	delegatedAuth
6823169a-2419-4015-b2fd-6fd6f026ca00	讨论
a85b8835-c1a1-4aac-ae97-1c3d0ba72dbd	distributedtask
7bf94c77-0ce1-44e5-a0f3-263e4ebbf327	drop
6c2b0933-3600-42ae-bf8b-93d4f7e83594	extensionManagement
67349c8b-6425-42f2-97b6-0843cb037473	收藏夹
4e080c62-fa21-4fbc-8fef-2a10a2b38049	git
4e40f190-2e3f-4d9f-8331-c7788e833080	graph
68ddce18-2501-45f1-a17b-7931a9922690	memberEntitlementManagement
b3be7473-68ea-4a81-bfc7-9530baaa19ad	NuGet
4c83cfc1-f33a-477e-a789-29d38ffca52e	npm
45fb9450-a28d-476d-9b0f-fb4aedddff73	包
7ab4e64e-c4d8-4f50-ae73-5ef2e21642a5	打包
2e0bf237-8973-4ec9-a581-9c3d679d1776	pipelines
fb13a388-40dd-4a04-b530-013a739c72ef	policy
8ccfef3d-2b87-4e99-8ccb-66e343d2daa8	个人资料
efc2f575-36ef-48e9-b672-0c6fb4a48ac5	发布
57731fdf-7d72-4678-83de-f8b31266e429	报告
ea48a0a1-269c-42d8-b8ad-ddc8fcdcf578	search
3b95fb80-fdda-4218-b60e-1052d070ae6b	测试
c83eaf52-edf3-4034-ae11-17d38f25404c	testresults
8aa40520-446d-40e6-89f6-9c9f9ce44c48	tfvc
970aa69f-e316-4d78-b7b0-b7137e47a22c	user
5264459e-e5e0-4bd8-b118-0985e68a4ec5	机智
1d4f49f9-02b9-4e26-b826-2cdb6195f2a9	工作
85f8c7b6-92fe-4ba6-8b6d-fbb67c809341	worktracking

后续步骤

公开扩展或集成