Usare gli URL nelle estensioni e nelle integrazioni

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

È possibile accedere alle risorse e alle API dell'organizzazione di Azure DevOps tramite due moduli URL:

Le API REST a livello di organizzazione accettano entrambi i moduli URL, indipendentemente dal momento in cui è stata creata l'organizzazione. Per altre informazioni, vedere Azure DevOps Services REST API Reference (Informazioni di riferimento sull'API REST di Azure DevOps Services).

URL primario

Ogni organizzazione ha un URL primario designato nel formato nuovo o legacy. Un amministratore può modificare l'URL primario. Il valore predefinito è basato su quando è stata creata l'organizzazione:

Come viene usato l'URL primario

Azure DevOps usa l'URL primario come base per tutti gli URL che costruisce nei processi in background e negli scenari automatizzati, tra cui:

• Variabili di ambiente dell'attività della pipeline (ad esempio SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)
• Payload degli eventi degli hook del servizio (ad esempio URL in resourceContainers)
• Posta elettronica, Slack, Microsoft Teams e notifiche simili

Ad esempio, il frammento di attività seguente visualizza l'URL dell'organizzazione:

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

L'output dipende dal modulo URL primario dell'organizzazione, https://dev.azure.com/{organization} ovvero o https://{organization}.visualstudio.com. Assicurarsi che entrambi i formati URL siano gestiti dalle attività delle pipeline e dai consumer di hook del servizio.

URL restituiti nelle API REST

Indipendentemente dall'URL primario di un'organizzazione, gli URL restituiti nella risposta a una chiamata API REST usano lo stesso URL di base dell'URL richiedente. Questa funzione garantisce che i client che chiamano un'API REST usando un URL legacy continuino a recuperare gli URL nello stesso formato (legacy). Ad esempio, quando l'API REST Projects viene chiamata usando un URL legacy, gli URL nella risposta usano il formato legacy:

Richiesta

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

Risposta

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

Chiamando la stessa API usando il nuovo URL (https://dev.azure.com/Fabrikam/_apis/projects/MyProject), gli URL vengono restituiti nella nuova forma URL.

Procedure consigliate

Per mantenere resiliente l'estensione, lo strumento o l'integrazione alle modifiche dell'URL:

• Non assumere una forma fissa dell'URL dell'organizzazione. Può cambiare nel tempo.
• Non analizzare o archiviare gli URL per costruire altri URL.
• Non presupporre che un'API REST risieda sempre nello stesso dominio.
• Usare le librerie client fornite da Microsoft (.NET, Node.js, Python) quando possibile, perché gestiscono automaticamente la risoluzione degli URL.

Ottenere l'URL di un'organizzazione

È possibile determinare l'URL di base di un'organizzazione dal nome o dall'ID utilizzando l'API REST globale delle Aree Risorse (https://dev.azure.com/_apis/resourceAreas). Questa API non richiede l'autenticazione.

Un'area di risorse è un gruppo di endpoint DELL'API REST correlati identificati da un GUID fisso. Ogni area di risorse può avere un URL di base diverso per ogni organizzazione. Ad esempio, le API di compilazione di Fabrikam possono usare , mentre le API https://dev.azure.com/Fabrikam usano https://vsrm.dev.azure.com/Fabrikam.

In base al nome dell'organizzazione

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

In base all'ID dell'organizzazione

Per risolvere l'URL in base al GUID dell'organizzazione anziché al nome, usare il parametro query hostId (anziché accountName):

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

Ottenere l'URL di base per un'API REST

Utilizzare l'API REST Aree di Risorsa a livello di organizzazione per cercare l'URL di base corretto per qualsiasi API REST. Questo approccio mantiene il codice resiliente quando i domini API cambiano.

Se non stai usando una libreria client:

1. Trovare l'ID dell'area di risorse per l'API necessaria nella tabella ID area risorsa. Il nome dell'area viene in genere visualizzato dopo /_apis/ nel percorso. Ad esempio, /_apis/release/definitions appartiene all'area release (aaaabbbb-0000-cccc-1111-dddd2222eeee).

2. Chiamare l'API REST Aree di Risorsa a livello di organizzazione con tale ID.

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

3. Usare il locationUrl campo dalla risposta come URL di base. In questo esempio, l'URL di base di Release Management è https://vsrm.dev.azure.com/Fabrikam.

Non sono necessarie credenziali per l'API REST Resource Areas.

Esempio: Chiamare l'API REST Release da un'attività della pipeline

Questa attività della pipeline risolve l'URL di base corretto per l'API REST Release usando l'URL dell'organizzazione dalla SYSTEM_TEAMFOUNDATIONCOLLECTIONURI variabile di ambiente.

$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 aree risorsa

Nella tabella seguente sono elencati gli ID per le aree di risorse comuni. Gli ID area delle risorse sono fissi e coerenti in tutte le organizzazioni di Azure DevOps Services.

Navigare a livello di codice con il servizio HostNavigationService

L'interfaccia IHostNavigationService consente alle estensioni di interagire con il frame host padre. Le estensioni possono usarlo per leggere e impostare l'hash URL, passare agli URL, ricaricare la pagina e gestire i parametri di query.

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

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

Valore hash

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

Navigazione e finestre

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

Ricaricare e documentare il titolo

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

Parametri di query

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

Per l'API completa, vedere IHostNavigationService e CommonServiceIds.

Passaggio successivo