Bekerja dengan URL dalam ekstensi dan integrasi

Artikel
05/30/2023

Azure DevOps

Dengan pengenalan Azure DevOps, sumber daya organisasi dan API sekarang dapat diakses melalui salah satu URL berikut:

https://dev.azure.com/{organization} (baru)
https://{organization}.visualstudio.com (warisan)

Terlepas dari kapan organisasi dibuat, pengguna, alat, dan integrasi dapat berinteraksi dengan REST API tingkat organisasi menggunakan salah satu URL. Sebagai pengembang ekstensi, integrasi, atau alat yang berinteraksi dengan Azure DevOps, pelajari cara terbaik bekerja dengan URL yang tersedia untuk kode dan URL formulir Anda saat Anda memanggil REST API.

Untuk informasi selengkapnya, lihat Referensi REST API.

URL utama organisasi

Setiap organisasi memiliki URL utama yang ditunjuk yang merupakan formulir baru atau formulir warisan. URL utama digunakan oleh Azure DevOps untuk membuat URL dalam skenario tertentu (detail selengkapnya mengikuti). URL utama default untuk organisasi ditentukan oleh kapan organisasi dibuat, tetapi dapat diubah oleh administrator:

Ketika organisasi dibuat	URL utama default
Pada atau setelah 10/9/2018	Baru
Sebelum 10/9/2018	Lama

Bagaimana URL utama digunakan

URL utama adalah URL dasar untuk semua URL yang dibangun oleh Azure DevOps dalam pekerjaan latar belakang dan skenario otomatis lainnya. Lihat contoh berikut.

URL yang disediakan untuk tugas Azure Pipelines melalui variabel lingkungan (seperti SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)
URL yang disertakan dalam payload peristiwa kait layanan (seperti URL di resourceContainers)
URL dalam email, Slack, Microsoft Teams, dan pemberitahuan serupa

Misalnya, cuplikan tugas berikut menampilkan URL organisasi yang disediakan untuk tugas:

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

Jika tugas ini dijalankan pada organisasi di mana URL utama adalah formulir URL baru, outputnya adalah https://dev.azure.com/{organization}. Tugas yang sama yang dijalankan pada organisasi di mana URL utama adalah output formulir URL warisan https://{organization}.visualstudio.com.

Oleh karena itu penting bahwa tugas dan layanan Azure Pipelines yang menerima peristiwa dari kait layanan menangani kedua formulir URL.

URL yang dikembalikan dalam REST API

Terlepas dari URL utama organisasi, URL yang dikembalikan sebagai respons terhadap panggilan REST API menggunakan URL dasar yang sama dengan URL yang meminta. Fungsi ini memastikan klien yang memanggil REST API menggunakan URL warisan terus mendapatkan kembali URL dalam bentuk yang sama (warisan). Misalnya, ketika REST API Proyek dipanggil menggunakan URL warisan, URL dalam respons menggunakan formulir warisan:

Minta

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

Respons

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

Memanggil API yang sama menggunakan URL baru (https://dev.azure.com/Fabrikam/_apis/projects/MyProject) menghasilkan URL yang dikembalikan dalam formulir URL baru.

Praktik terbaik

Untuk memastikan ekstensi, alat, atau integrasi Anda tahan terhadap perubahan formulir URL organisasi dan untuk kemungkinan perubahan di masa mendatang pada lokasi (domain) REST API:

Asumsikan bentuk URL organisasi dapat berubah dari waktu ke waktu.
Hindari mengurai URL untuk membuat URL lain.
Jangan asumsikan REST API tertentu selalu berada di domain yang sama.
Hindari menyimpan URL di layanan Anda.
Jika memungkinkan, gunakan pustaka klien .NET, TypeScript (web), Node.js, dan Python yang disediakan Microsoft dengan Azure DevOps.

Cara mendapatkan URL organisasi

Hanya dengan nama atau ID organisasi, Anda bisa mendapatkan URL dasarnya menggunakan REST API Area Sumber Daya global (https://dev.azure.com/_apis/resourceAreas). API ini tidak memerlukan autentikasi. Ini juga menyediakan informasi tentang lokasi (URL) organisasi dan URL dasar untuk REST API, yang dapat hidup di domain yang berbeda.

Area sumber daya adalah sekelompok sumber daya dan titik akhir REST API terkait. Setiap area sumber daya memiliki pengidentifikasi terkenal (lihat tabel berikut). Setiap area sumber daya memiliki URL dasar khusus organisasi yang dapat digunakan untuk membentuk URL untuk API di area sumber daya tersebut. Misalnya, URL dasar untuk REST API "build" untuk Fabrikam mungkin https://dev.azure.com/Fabrikam, tetapi URL dasar untuk REST API "manajemen rilis" mungkin .https://vsrm.dev.azure.com/Fabrikam

Catatan

REST API Area Sumber Daya mengembalikan URL untuk organisasi berdasarkan URL utama yang ditunjuk organisasi tersebut.

Dengan nama organisasi

Ada beberapa cara untuk mendapatkan URL dasar untuk organisasi menggunakan namanya.

Minta

Ganti {organizationName} dengan nama organisasi, misalnya "Fabrikam". 79134C72-4A58-4B42-976C-04E7115F32BF adalah ID untuk area sumber daya "inti", di mana sumber daya penting seperti "proyek" berada.

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

Respons

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

mencerminkan locationUrl URL dasar organisasi.

Pustaka klien .NET yang disediakan Microsoft (Microsoft.VisualStudio.Services.Client) menyediakan kelas pembantu yang memanggil REST API Area Sumber Daya untuk Anda dan mengembalikan URL dasar untuk organisasi.

Catatan

Kelas VssConnectionHelper tersedia dalam versi 16.139.0-preview dan versi pustaka klien yang lebih baru.

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
}

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

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);
});

Dengan ID organisasi

Untuk mendapatkan URL untuk organisasi menggunakan pengidentifikasi GUID-nya, gunakan hostId parameter kueri dalam contoh sebelumnya (bukan accountName). Contohnya:

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

Cara mendapatkan URL dasar untuk REST API

Mulai dari URL organisasi, Anda dapat menggunakan REST API Area Sumber Daya untuk mencari URL dasar yang benar untuk REST API apa pun yang perlu Anda panggil. Proses ini memastikan kode Anda tahan terhadap lokasi (domain) REST API yang berubah di masa mendatang dan menghindari logika yang berpotensi rapuh.

Catatan

Jika Anda menggunakan pustaka klien .NET, TypeScript (web), Node.js, atau Python yang disediakan Microsoft, pencarian URL akan ditangani untuk Anda. Misalnya, di .NET saat Anda membuat VssConnection dan memanggil GetClient<T>, klien yang dikembalikan terikat dengan benar ke URL dasar yang benar untuk REST API yang dipanggil oleh klien ini.

Jika Anda tidak menggunakan pustaka klien yang disediakan Microsoft:

Gunakan tabel berikut untuk menemukan ID area sumber daya untuk REST API yang perlu Anda panggil. Nama area sumber daya biasanya muncul setelah /_apis/ di rute REST API. Misalnya, /_apis/release/definitions REST API milik release area sumber daya, yang memiliki ID .efc2f575-36ef-48e9-b672-0c6fb4a48ac5
Panggil REST API Area Sumber Daya tingkat organisasi ({organizationUrl}/_apis/resourceAreas/{resourceAreaId}?api-version=5.0-preview.1) dan berikan ID area sumber daya. Contohnya:
```
GET https://dev.azure.com/Fabrikam/_apis/resourceAreas/efc2f575-36ef-48e9-b672-0c6fb4a48ac5?api-version=5.0-preview.1
```
locationUrl Gunakan bidang dari respons JSON sebagai URL dasar untuk memanggil REST API lain untuk area ini. Dalam contoh ini, URL dasar untuk REST API Manajemen Rilis adalah https://vsrm.dev.azure.com/Fabrikam.

Seperti REST API Area Sumber Daya global yang dijelaskan sebelumnya, tidak ada kredensial yang diperlukan untuk memanggil REST API Area Sumber Daya tingkat organisasi.

Contoh: Tugas alur yang memanggil REST API rilis Azure Pipelines

Dalam contoh ini, tugas build perlu memanggil REST API rilis Azure Pipelines. Ini membentuk URL dasar yang benar untuk panggilan REST API ini dengan menggunakan URL organisasi (disediakan dalam variabel lingkungan) dan REST API Area Sumber Daya.

Catatan

ID area sumber daya diperbaiki dan dapat disematkan dengan aman dalam tugas dan logika lainnya.

$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 area sumber daya (referensi)

Tabel ini memperlihatkan ID untuk area sumber daya umum. Lihat bagian sebelumnya untuk detail tentang cara menggunakan tabel ini.

Catatan

ID area sumber daya diperbaiki dan konsisten di semua organisasi di Azure DevOps Services.

ID Area Sumber Daya	Nama
0d55247a-1c47-4462-9b1f-5e2125590ee6	akun
5d6898bb-45ec-463f-95f9-54d49c71752e	build
79bea8f8-c898-4965-8c51-8bbc3966faa8	koleksi
79134c72-4a58-4b42-976c-04e7115f32bf	core
31c84e0a-3ece-48fd-a29d-100849af99ba	dasbor
a0848fa1-3593-4aec-949c-694c73f4c4ce	delegatedAuth
6823169a-2419-4015-b2fd-6fd6f026ca00	Diskusi
a85b8835-c1a1-4aac-ae97-1c3d0ba72dbd	distributedtask
7bf94c77-0ce1-44e5-a0f3-263e4ebbf327	hilangkan
6c2b0933-3600-42ae-bf8b-93d4f7e83594	extensionManagement
67349c8b-6425-42f2-97b6-0843cb037473	Favorit
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	paket
7ab4e64e-c4d8-4f50-ae73-5ef2e21642a5	packaging
2e0bf237-8973-4ec9-a581-9c3d679d1776	alur
fb13a388-40dd-4a04-b530-013a739c72ef	kebijakan
8ccfef3d-2b87-4e99-8ccb-66e343d2daa8	profil
efc2f575-36ef-48e9-b672-0c6fb4a48ac5	Rilis
57731fdf-7d72-4678-83de-f8b31266e429	pelaporan
ea48a0a1-269c-42d8-b8ad-ddc8fcdcf578	pencarian
3b95fb80-fdda-4218-b60e-1052d070ae6b	uji
c83eaf52-edf3-4034-ae11-17d38f25404c	testresults
8aa40520-446d-40e6-89f6-9c9f9ce44c48	tfvc
970aa69f-e316-4d78-b7b0-b7137e47a22c	pengguna
5264459e-e5e0-4bd8-b118-0985e68a4ec5	Kecerdasan
1d4f49f9-02b9-4e26-b826-2cdb6195f2a9	kerja
85f8c7b6-92fe-4ba6-8b6d-fbb67c809341	worktracking

Langkah berikutnya

Membuat ekstensi atau integrasi Anda menjadi publik

Bagikan melalui

Bekerja dengan URL dalam ekstensi dan integrasi

URL utama organisasi

Bagaimana URL utama digunakan

URL yang dikembalikan dalam REST API

Minta

Respons

Praktik terbaik

Cara mendapatkan URL organisasi

Dengan nama organisasi

Minta

Respons

Dengan ID organisasi

Cara mendapatkan URL dasar untuk REST API

Contoh: Tugas alur yang memanggil REST API rilis Azure Pipelines

ID area sumber daya (referensi)

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: