拡張機能と統合で URL を操作する

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022

Azure DevOps 組織のリソースと API には、次の 2 つの URL 形式でアクセスできます。

組織レベルの REST API は、組織の作成時に関係なく、どちらの URL フォームも受け入れます。 詳細については、 Azure DevOps Services REST API リファレンスを参照してください。

プライマリ URL

各組織には、新しい形式またはレガシ形式で指定された プライマリ URL があります。 管理者はプライマリ URL を変更できます。 既定値は、組織を作成した日時に基づいています。

プライマリ URL の使用方法

Azure DevOps は、バックグラウンド ジョブおよび自動化されたシナリオで構築するすべての URL のベースとしてプライマリ URL を使用します。

• パイプライン タスク環境変数 ( SYSTEM_TEAMFOUNDATIONCOLLECTIONURI など)
• サービスはイベント ペイロード ( resourceContainers の URL など) をフックします
• 電子メール、Slack、Microsoft Teams、および同様の通知

たとえば、次のタスク スニペットは組織の URL を表示します。

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

出力は、組織のプライマリ URL フォーム ( https://dev.azure.com/{organization} または https://{organization}.visualstudio.com) によって異なります。 パイプライン タスクとサービス フック コンシューマーが両方の URL フォームを処理していることを確認します。

REST API で返される URL

組織のプライマリ URL に関係なく、REST API 呼び出しに対する応答で返される URL は、要求元の URL と同じベース URL を使用します。 この関数により、レガシ URL を使用して REST API を呼び出すクライアントは、同じ (レガシ) 形式で URL を引き続き取得できます。 たとえば、Projects REST API がレガシ URL を使用して呼び出されると、応答内の URL は従来の形式を使用します。

リクエスト

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

[応答]

{
  "id": "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
  "name": "MyProject",
  "url": "https://Fabrikam.visualstudio.com/_apis/projects/MyProject"
}

新しい URL (https://dev.azure.com/Fabrikam/_apis/projects/MyProject) を使用して同じ API を呼び出すと、新しい URL 形式で URL が返されます。

ベスト プラクティス

拡張機能、ツール、または統合を URL の変更に対する回復性を維持するには:

• 固定の組織の URL フォームを想定しないでください。 時間の経過と同時に変化する可能性があります。
• 他の URL を作成するために URL を解析または格納しないでください。
• REST API が常に同じドメイン上にあると想定しないでください。
• 可能な場合は、Microsoft が提供するクライアント ライブラリ (.NET、 Node.js、 Python) を使用します。URL 解決は自動的に処理されるためです。

組織の URL を取得する

グローバル リソース領域 REST API (https://dev.azure.com/_apis/resourceAreas) を使用して、組織のベース URL を名前または ID から解決できます。 この API では認証は必要ありません。

リソース領域は、固定 GUID によって識別される、関連する REST API エンドポイントのグループです。 各リソース領域には、組織ごとに異なるベース URL を設定できます。 たとえば、Fabrikam の ビルド API では https://dev.azure.com/Fabrikamを使用し、 リリース管理 API では https://vsrm.dev.azure.com/Fabrikamを使用します。

組織名別

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

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

public async Task MyMethod()
{
    string organizationName = "Fabrikam";
    VssCredentials credentials = new VssBasicCredential(string.Empty, "your-pat");

    Uri organizationUrl = await VssConnectionHelper.GetOrganizationUrlAsync(organizationName);
    VssConnection connection = new VssConnection(organizationUrl, credentials);

    // Use connection.GetClient<T>() to call APIs
}

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

static readonly HttpClient s_client = new HttpClient();
const string CoreResourceAreaId = "79134C72-4A58-4B42-976C-04E7115F32BF";

public async Task<Uri?> GetOrganizationUrl(string organizationName)
{
    string requestUrl = $"https://dev.azure.com/_apis/resourceAreas/{CoreResourceAreaId}?accountName={organizationName}&api-version=5.0-preview.1";

    var response = await s_client.GetAsync(requestUrl);

    if (response.StatusCode == HttpStatusCode.OK)
    {
        var resourceArea = await response.Content.ReadFromJsonAsync<JsonElement>();
        string? locationUrl = resourceArea.GetProperty("locationUrl").GetString();
        if (locationUrl != null)
        {
            return new Uri(locationUrl);
        }
    }

    return null;
}

const coreResourceAreaId = "79134C72-4A58-4B42-976C-04E7115F32BF";

async function getOrgUrl(orgName) {
    const url = `https://dev.azure.com/_apis/resourceAreas/${coreResourceAreaId}?accountName=${orgName}&api-version=5.0-preview.1`;
    const response = await fetch(url);

    if (response.ok) {
        const body = await response.json();
        return body.locationUrl;
    }

    return null;
}

const orgUrl = await getOrgUrl("fabrikam");
console.log(orgUrl);

組織 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 を取得する

組織レベルのリソース領域 REST API を使用して、任意の REST API の正しいベース URL を検索します。 この方法により、API ドメインが変更されたときにコードの回復性が維持されます。

クライアント ライブラリを使用していない場合:

1. リソース領域 ID テーブルで、必要な API の リソース領域 ID を見つけます。 エリア名は、通常、ルート内の /_apis/ の後に表示されます。 たとえば、 /_apis/release/definitions は release 領域 (aaaabbbb-0000-cccc-1111-dddd2222eeee) に属します。

2. 組織レベルの Resource Areas REST API をその ID で呼び出します。

   GET https://dev.azure.com/Fabrikam/_apis/resourceAreas/aaaabbbb-0000-cccc-1111-dddd2222eeee?api-version=5.0-preview.1
   

3. 応答の locationUrl フィールドをベース URL として使用します。 この例では、リリース管理のベース URL が https://vsrm.dev.azure.com/Fabrikam。

Resource Areas REST API には資格情報は必要ありません。

例: パイプライン タスクから Releases REST API を呼び出す

このパイプライン タスクは、 SYSTEM_TEAMFOUNDATIONCOLLECTIONURI 環境変数の組織の URL を使用して、Releases REST API の正しいベース URL を解決します。

$orgUrl = $env:SYSTEM_TEAMFOUNDATIONCOLLECTIONURI
$releaseManagementAreaId = "aaaabbbb-0000-cccc-1111-dddd2222eeee"

# Look up the base URL for Release Management APIs
$orgResourceAreasUrl = "${orgUrl}_apis/resourceAreas/${releaseManagementAreaId}?api-version=5.0-preview.1"
$results = Invoke-RestMethod -Uri $orgResourceAreasUrl
$rmUrl = $results.locationUrl

# Call the release definitions API
$releaseDefinitionsUrl = "${rmUrl}/_apis/release/definitions?api-version=5.0-preview.1"

リソース領域 ID

次の表に、一般的なリソース領域の ID を示します。 リソース領域 ID は、すべての Azure DevOps Services 組織で固定され、一貫性があります。

HostNavigationService を使用してプログラムで移動する

IHostNavigationService インターフェイスを使用すると、拡張機能は親ホスト フレームと対話できます。 拡張機能は、これを使用して、URL ハッシュの読み取りと設定、URL への移動、ページの再読み込み、クエリ パラメーターの管理を行うことができます。

import * as SDK from "azure-devops-extension-sdk";
import { CommonServiceIds, IHostNavigationService } from "azure-devops-extension-api";

const navService = await SDK.getService<IHostNavigationService>(CommonServiceIds.HostNavigationService);

ハッシュ値

// Get the current hash
const hash = await navService.getHash();
console.log("Host hash value: " + hash);

// Listen for hash changes
navService.onHashChanged((hash: string) => {
    console.log("Hash changed to: " + hash);
});

// Set hash (adds a new browser history entry)
navService.setHash("new-hash-value");

// Replace hash (no new history entry)
navService.replaceHash("replaced-hash-value");

ナビゲーションとウィンドウ

// Navigate the host page
navService.navigate("https://dev.azure.com/myorg/myproject");

// Open a new browser window
navService.openNewWindow("https://dev.azure.com/myorg/myproject", "height=400,width=600");

再読み込みとドキュメント タイトル

navService.reload();
navService.setDocumentTitle("My Custom Page Title");

クエリ パラメーター

// Get current query parameters
const params = await navService.getQueryParams();
console.log(params);

// Set query parameters (pass empty string to remove a parameter)
navService.setQueryParams({ myParam: "value", removeMe: "" });

完全な API については、 IHostNavigationService と CommonServiceIds を参照してください。

次のステップ