Arbeiten mit URLs in Erweiterungen und Integrationen

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

Sie können über zwei URL-Formulare auf Azure DevOps-Organisationsressourcen und -APIs zugreifen:

REST-APIs auf Organisationsebene akzeptieren beide URL-Formulare, unabhängig davon, wann Sie die Organisation erstellt haben. Weitere Informationen finden Sie in der REST-API-Referenz zu Azure DevOps Services.

Primäre URL

Jede Organisation verfügt über eine festgelegte primäre URL im neuen oder älteren Formular. Ein Administrator kann die primäre URL ändern. Die Standardeinstellung basiert auf dem Zeitpunkt, an dem Sie die Organisation erstellt haben:

Verwendung der primären URL

Azure DevOps verwendet die primäre URL als Basis für alle URLs, die sie in Hintergrundaufträgen und automatisierten Szenarien erstellt, darunter:

• Umgebungsvariablen für Pipelineaufgaben (z. B SYSTEM_TEAMFOUNDATIONCOLLECTIONURI. )
• Dienst-Hooks Ereignis Payloads (wie URLs in resourceContainers)
• E-Mail, Slack, Microsoft Teams und ähnliche Benachrichtigungen

Der folgende Aufgabenausschnitt zeigt beispielsweise die Organisations-URL an:

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

Die Ausgabe hängt vom primären URL-Formular der Organisation ab – entweder https://dev.azure.com/{organization} oder https://{organization}.visualstudio.com. Stellen Sie sicher, dass Ihre Pipelines Tasks und Dienst-Hooks Consumer beide URL-Formen verarbeiten.

In REST-APIs zurückgegebene URLs

Unabhängig von der primären URL einer Organisation verwenden URLs, die in der Antwort auf einen REST-API-Aufruf zurückgegeben werden, dieselbe Basis-URL wie die anfordernde URL. Diese Funktion stellt sicher, dass Clients, die eine REST-API mit einer Legacy-URL aufrufen, weiterhin URLs im selben (Legacy)-Formular abrufen. Wenn beispielsweise die Projects-REST-API mithilfe einer Legacy-URL aufgerufen wird, verwenden URLs in der Antwort das Legacyformular:

Anfrage

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

Antwort

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

Das Aufrufen derselben API mithilfe der neuen URL (https://dev.azure.com/Fabrikam/_apis/projects/MyProject) führt zu URLs, die im neuen URL-Formular zurückgegeben werden.

Bewährte Methoden

So halten Sie Ihre Erweiterung, Ihr Tool oder Ihre Integration für URL-Änderungen widerstandsfähig:

• Gehen Sie nicht von einem festen Organisations-URL-Formular aus. Sie kann sich im Laufe der Zeit ändern.
• Analysieren oder speichern Sie keine URLs, um andere URLs zu erstellen.
• Gehen Sie nicht davon aus, dass sich eine REST-API immer in derselben Domäne befindet.
• Verwenden Sie nach Möglichkeit von Microsoft bereitgestellte Clientbibliotheken (.NET, Node.js, Python), da sie die URL-Auflösung automatisch verarbeiten.

Abrufen der URL einer Organisation

Sie können die Basis-URL einer Organisation anhand ihres Namens oder ihrer ID auflösen, indem Sie die globale REST-API der Resource Areas verwendenhttps://dev.azure.com/_apis/resourceAreas. Diese API erfordert keine Authentifizierung.

Ein Ressourcenbereich ist eine Gruppe verwandter REST-API-Endpunkte, die durch eine feste GUID identifiziert werden. Jeder Ressourcenbereich kann eine andere Basis-URL für jede Organisation haben. Die Build-APIs von Fabrikam könnten zum Beispiel https://dev.azure.com/Fabrikam verwenden, während die Release Management-APIs https://vsrm.dev.azure.com/Fabrikam verwenden.

Nach Organisationsname

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

Nach Organisations-ID

Um die URL anhand der Organisations-GUID anstelle des Namens aufzulösen, verwenden Sie den Abfrageparameter hostId (anstelle von accountName).

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

Abrufen der Basis-URL für eine REST-API

Verwenden Sie die REST-API auf Organisationsebene, um die richtige Basis-URL für jede REST-API nachzuschlagen. Dieser Ansatz sorgt dafür, dass Ihr Code stabil bleibt, wenn sich API-Domänen ändern.

Wenn Sie keine Clientbibliothek verwenden:

1. Suchen Sie die Ressourcenbereichs-ID für die API, die Sie in der Tabelle "Ressourcenbereichs-ID" benötigen. Der Bereichsname erscheint in der Regel nach /_apis/ in der Route. Gehört z. B /_apis/release/definitions . zum release Bereich (aaaabbbb-0000-cccc-1111-dddd2222eeee).

2. Rufen Sie die REST-API für Ressourcenbereiche auf Organisationsebene mit dieser ID auf:

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

3. Verwenden Sie das locationUrl Feld aus der Antwort als Basis-URL. In diesem Beispiel lautet https://vsrm.dev.azure.com/Fabrikamdie Basis-URL für die Versionsverwaltung .

Für die REST-API für Ressourcenbereiche sind keine Anmeldeinformationen erforderlich.

Beispiel: Aufrufen der Releases-REST-API aus einer Pipelineaufgabe

Diese Pipelineaufgabe löst die richtige Basis-URL für die Releases-REST-API mithilfe der Organisations-URL aus der SYSTEM_TEAMFOUNDATIONCOLLECTIONURI Umgebungsvariable auf.

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

Ressourcenbereich-IDs

In der folgenden Tabelle sind IDs für allgemeine Ressourcenbereiche aufgeführt. Ressourcenbereich-IDs sind in allen Azure DevOps Services-Organisationen fest und konsistent.

Programmgesteuertes Navigieren mit dem HostNavigationService

Die IHostNavigationService Schnittstelle ermöglicht Erweiterungen die Interaktion mit dem übergeordneten Host Frame. Erweiterungen können ihn verwenden, um den URL-Hash zu lesen und festzulegen, zu URLs zu navigieren, die Seite neu zu laden und Abfrageparameter zu verwalten.

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

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

Hashwert

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

Navigation und Fenster

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

Neuladen und Dokumenttitel

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

Abfrageparameter

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

Die vollständige API finden Sie unter "IHostNavigationService " und "CommonServiceIds".

Nächster Schritt