Praca z adresami URL w rozszerzeniach i integracjach

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

Dostęp do zasobów organizacyjnych i interfejsów API usługi Azure DevOps można uzyskać za pomocą dwóch formularzy adresów URL:

Formularz adresu URL	Przykład
Nowy	https://dev.azure.com/{organization}
Dziedzictwo	https://{organization}.visualstudio.com

Interfejsy API REST na poziomie organizacji akceptują dowolny formularz adresu URL niezależnie od tego, kiedy została utworzona organizacja. Więcej informacji znajdziesz w Odnośniku do interfejsu API REST usługi Azure DevOps Services.

Podstawowy adres URL

Każda organizacja ma wyznaczony podstawowy adres URL w nowym lub starszym formularzu. Administrator może zmienić podstawowy adres URL. Wartość domyślna jest oparta na czasie utworzenia organizacji.

Created	Domyślny podstawowy adres URL
10 września 2018 r. lub później	Nowy
Przed 10 września 2018 r.	Dziedzictwo

Jak jest używany podstawowy adres URL

Usługa Azure DevOps używa podstawowego adresu URL jako podstawy dla wszystkich adresów URL, które tworzy w zadaniach w tle i zautomatyzowanych scenariuszach, w tym:

• Zmienne środowiskowe zadania pipeline (takie jak SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)
• Ładunki zdarzeń punktów zaczepienia usługi (na przykład adresy URL w programie resourceContainers)
• Wiadomości e-mail, Slack, Microsoft Teams i podobne powiadomienia

Na przykład poniższy fragment kodu zadania wyświetla adres URL organizacji:

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

Dane wyjściowe zależą od podstawowego formularza adresu URL organizacji — https://dev.azure.com/{organization} lub https://{organization}.visualstudio.com. Upewnij się, że zadania potoków i odbiorcy webhooków obsługują oba formaty adresów URL.

Adresy URL zwracane w interfejsach API REST

Niezależnie od podstawowego adresu URL organizacji adresy URL zwrócone w odpowiedzi na wywołanie interfejsu API REST używają tego samego podstawowego adresu URL co żądany adres URL. Ta funkcja zapewnia, że klienci wywołujący interfejs API REST przy użyciu starszego adresu URL będą nadal uzyskiwać adresy URL w tym samym (starszym) formacie. Na przykład gdy interfejs API REST projektów jest wywoływany przy użyciu starszego adresu URL, adresy URL w odpowiedzi używają starszego formularza:

Żądanie

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

Odpowiedź

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

Wywołanie tego samego interfejsu API przy użyciu nowego adresu URL (https://dev.azure.com/Fabrikam/_apis/projects/MyProject) powoduje zwrócenie adresów URL w nowym formacie adresu URL.

Najlepsze rozwiązania

Aby zapewnić odporność rozszerzenia, narzędzia lub integracji na zmiany adresów URL:

• Nie zakładaj stałego formatu adresu URL dla organizacji. Może się to zmienić w czasie.
• Nie analizuj ani nie przechowuj adresów URL w celu konstruowania innych adresów URL.
• Nie zakładaj, że interfejs API REST zawsze znajduje się w tej samej domenie.
• Jeśli to możliwe, użyj bibliotek klienckich udostępnianych przez firmę Microsoft (.NET, Node.js, Python), ponieważ obsługują one automatyczne rozpoznawanie adresów URL.

Uzyskiwanie adresu URL organizacji

Podstawowy adres URL organizacji można ustalić na podstawie jej nazwy lub identyfikatora, używając globalnego interfejsu API REST stref zasobów (https://dev.azure.com/_apis/resourceAreas). Ten interfejs API nie wymaga uwierzytelniania.

Obszar zasobów to grupa powiązanych punktów końcowych interfejsu API REST zidentyfikowanych przez stały identyfikator GUID. Każdy obszar zasobów może mieć inny podstawowy adres URL dla każdej organizacji. Na przykład interfejsy API kompilacji firmy Fabrikam mogą używać https://dev.azure.com/Fabrikam, a interfejsy API zarządzania wydaniami używają https://vsrm.dev.azure.com/Fabrikam.

Uwaga / Notatka

Interfejs REST API Obszarów Zasobów zwraca URL-e na bazie wyznaczonego podstawowego adresu URL organizacji.

Według nazwy organizacji

Protokół HTTP

Zastąp {organizationName} nazwą organizacji. Identyfikator GUID 79134C72-4A58-4B42-976C-04E7115F32BF identyfikuje podstawowy obszar zasobów, który zawiera zasoby, takie jak projekty.

Żądanie

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

Odpowiedź

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

Pole locationUrl zawiera podstawowy adres URL organizacji.

C# (biblioteka klienta)

Biblioteka klienta platformy .NET dostarcza VssConnectionHelper, który wywołuje REST API obszarów zasobów i zwraca podstawowy adres URL organizacji.

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
}

C# (generyczny)

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

Node.js

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

Według identyfikatora organizacji

Aby rozpoznać adres URL według identyfikatora GUID organizacji zamiast nazwy, użyj parametru hostId zapytania (zamiast accountName):

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

Uzyskiwanie podstawowego adresu URL dla interfejsu API REST

Użyj interfejsu API REST obszarów zasobów na poziomie organizacji, aby wyszukać prawidłowy podstawowy adres URL dla dowolnego interfejsu API REST. Takie podejście zapewnia odporność kodu w przypadku zmiany domen interfejsu API.

Uwaga / Notatka

Biblioteki klienckie dostarczone przez firmę Microsoft (.NET, TypeScript, Node.js, Python) automatycznie obsługują wyszukiwanie adresów URL. Na przykład VssConnection.GetClient<T>() na platformie .NET zwraca klienta, który jest już powiązany z poprawnym podstawowym adresem URL.

Jeśli nie używasz biblioteki klienta:

1. Znajdź identyfikator obszaru zasobów dla interfejsu API potrzebnego w tabeli identyfikatorów obszaru zasobów. Nazwa obszaru zwykle występuje po /_apis/ na trasie. Na przykład /_apis/release/definitions należy do release obszaru (aaaabbbb-0000-cccc-1111-dddd2222eeee).

2. Wywołaj interfejs API REST stref zasobów na poziomie organizacji, używając tego identyfikatora:

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

3. locationUrl Użyj pola z odpowiedzi jako podstawowego adresu URL. W tym przykładzie podstawowy adres URL usługi Release Management to https://vsrm.dev.azure.com/Fabrikam.

Dla interfejsu API REST obszarów zasobów nie są wymagane żadne poświadczenia.

Przykład: wywoływanie interfejsu API REST Releases z zadania pipeline'u

To zadanie potoku ustala prawidłowy podstawowy adres URL dla interfejsu API REST wydawnictw, używając adresu URL organizacji ze zmiennej środowiskowej SYSTEM_TEAMFOUNDATIONCOLLECTIONURI.

Uwaga / Notatka

Identyfikatory obszaru zasobów są stałe i można je bezpiecznie osadzać w zadaniach i innej logice.

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

Identyfikatory obszaru zasobów

W poniższej tabeli wymieniono identyfikatory typowych obszarów zasobów. Identyfikatory obszarów zasobów są stałe i spójne we wszystkich organizacjach usługi Azure DevOps Services.

Identyfikator obszaru zasobów	Nazwa
0D55247A-1C47-4462-9B1F-5E2125590ee6	konto
5D6898BB-45EC-463F-95F9-54D49C71752E	kompilacja
79bea8f8-c898-4965-8c51-8bbc3966faa8	kolekcja
79134C72-4A58-4B42-976C-04E7115F32BF	rdzeń
31C84E0A-3ECE-48FD-A29D-100849AF99BA	pulpit nawigacyjny
A0848FA1-3593-4AEC-949C-694C73F4C4CE	delegowane uwierzytelnianie
6823169a-2419-4015-b2fd-6fd6f026ca00	dyskusja
A85B8835-C1A1-4AAC-AE97-1C3D0BA72DBD	zadanie rozproszone
7BF94C77-0CE1-44E5-A0F3-263E4EBBF327	porzucić
6C2B0933-3600-42AE-BF8B-93D4F7E83594	zarządzanie rozszerzeniami
67349C8B-6425-42F2-97B6-0843CB037473	dodać do Ulubionych
4E080C62-FA21-4FBC-8FEF-2A10A2B38049	Git
4E40F190-2E3F-4D9F-8331-C7788E833080	graf
68dce18-2501-45f1-a17b-7931a9922690	zarządzanie uprawnieniami członków
B3BE7473-68EA-4A81-BFC7-9530BAAA19AD	NuGet
4C83CFC1-F33A-477E-A789-29D38FFCA52E	npm
45FB9450-A28D-476D-9B0F-FB4AEDDFF73	pakiet
7AB4E64E-C4D8-4F50-AE73-5EF2E21642A5	opakowanie
2e0bf237-8973-4ec9-a581-9c3d679d1776	Rurociągi
FB13A388-40DD-4A04-B530-013A739C72EF	zasady
8CCFEF3D-2B87-4E99-8CCB-66E343D2DAA8	profil
aaaabbbb-0000-cccc-1111-dddd2222eeee	wersja
57731FDF-7D72-4678-83DE-F8B31266E429	raportowanie
EA48A0A1-269C-42D8-B8AD-DDC8FCDCF578	wyszukać
3B95FB80-FDDA-4218-B60E-1052D070AE6B	test
C83EAF52-EDF3-4034-AE11-17D38F25404C	wyniki testów
8AA40520-446D-40E6-89F6-9C9F9CE44C48	TFVC
970AA69F-E316-4D78-B7B0-B7137E47A22C	użytkownik
5264459e-e5e0-4bd8-b118-0985e68a4ec5	dowcip i inteligencja
1D4F49F9-02B9-4E26-B826-2CDB6195F2A9	praca
85F8C7B6-92FE-4BA6-8B6D-FBB67C809341	śledzenie pracy

Programowe nawigowanie za pomocą elementu HostNavigationService

Interfejs IHostNavigationService umożliwia rozszerzeniom interakcję z ramką hosta nadrzędnego. Rozszerzenia mogą jej używać do odczytywania i ustawiania skrótu adresu URL, przechodzenia do adresów URL, ponownego ładowania strony i zarządzania parametrami zapytania.

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

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

Wartość skrótu

// 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");

Nawigacja i okna

// 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");

Załaduj ponownie i tytuł dokumentu

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

Parametry zapytania

// 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: "" });

Aby uzyskać pełny interfejs API, zobacz IHostNavigationService i CommonServiceIds.

Następny krok

Upublicznij rozszerzenie lub integrację