Arbeta med URL:er i tillägg och integreringar

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

Du kan komma åt Azure DevOps-organisationsresurser och API:er via två URL-formulär:

URL-formulär	Exempel
Nytt	`https://dev.azure.com/{organization}`
Arv	`https://{organization}.visualstudio.com`

REST-API:er på organisationsnivå accepterar antingen URL-formulär, oavsett när du skapade organisationen. Mer information finns i REST API-referensen för Azure DevOps Services.

Primär URL

Varje organisation har en utsedd primär URL i antingen det nya eller äldre formuläret. En administratör kan ändra den primära URL:en. Standardinställningen baseras på när du skapade organisationen:

Skapades	Standard primär URL
Den 10 september 2018 eller senare	Nytt
Före den 10 september 2018	Arv

Hur den primära URL:en används

Azure DevOps använder den primära URL:en som bas för alla URL:er som skapas i bakgrundsjobb och automatiserade scenarier, inklusive:

Miljövariabler för pipelineaktivitet (till exempel SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)
Service Hooks-händelsenyttolaster (till exempel URL:er i resourceContainers)
E-post, Slack, Microsoft Teams och liknande meddelanden

Följande aktivitetsfragment visar till exempel organisationens URL:

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

Utdata beror på organisationens primära URL-formulär – antingen https://dev.azure.com/{organization} eller https://{organization}.visualstudio.com. Kontrollera att dina pipeline-uppgifter och tjänstkrokskonsumenter hanterar båda formerna av URL.

URL:er som returneras i REST-API:er

Oavsett organisationens primära URL använder URL:er som returneras i svaret på ett REST API-anrop samma bas-URL som den begärda URL:en. Den här funktionen säkerställer att klienter som anropar ett REST API med en äldre URL fortsätter att hämta url:er i samma (äldre) formulär. När till exempel Project REST API anropas med hjälp av en äldre URL använder URL:er i svaret det äldre formuläret:

Begäran

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

Svar

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

Om du anropar samma API med hjälp av den nya URL:en (https://dev.azure.com/Fabrikam/_apis/projects/MyProject) returneras URL:er i det nya URL-formuläret.

Metodtips

Så här håller du tillägget, verktyget eller integreringen motståndskraftig mot URL-ändringar:

Anta inte ett fast organisations-URL-format. Det kan ändras med tiden.
Parsa eller lagra inte URL:er för att konstruera andra URL:er.
Anta inte att ett REST-API alltid finns på samma domän.
Använd Microsoft-tillhandahållna klientbibliotek (.NET, Node.js, Python) när det är möjligt, eftersom de hanterar URL-matchning automatiskt.

Hämta en organisations URL

Du kan lösa en organisations bas-URL från dess namn eller ID med hjälp av det globala REST-API:et för resursområden (https://dev.azure.com/_apis/resourceAreas). Det här API:et kräver inte autentisering.

Ett resursområde är en grupp relaterade REST API-slutpunkter som identifieras av ett fast GUID. Varje resursområde kan ha en annan bas-URL för varje organisation. Fabrikams bygg-API:er kan till exempel använda https://dev.azure.com/Fabrikam, medan Versionshanterings-API:er använder https://vsrm.dev.azure.com/Fabrikam.

Anmärkning

REST-API:et för resursområden returnerar URL:er baserat på organisationens avsedda primära URL.

Efter organisationsnamn

Ersätt {organizationName} med organisationens namn. GUID 79134C72-4A58-4B42-976C-04E7115F32BF identifierar kärnresursområdet , som innehåller resurser som projekt.

Begäran

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

Svar

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

Fältet locationUrl innehåller organisationens bas-URL.

.NET-klientbiblioteket innehåller VssConnectionHelper, som anropar REST-API:et för resursområden och returnerar organisationens bas-URL.

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

Efter organisations-ID

Lös URL:en genom att använda organisations-GUID i stället för namn, med hjälp av frågeparametern hostId (i stället för accountName):

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

Hämta bas-URL:en för ett REST-API

Använd REST-API för resursområden på organisationsnivå för att hitta rätt bas-URL för valfritt REST-API. Den här metoden håller koden elastisk när API-domäner ändras.

Anmärkning

Microsoft-tillhandahållna klientbibliotek (.NET, TypeScript, Node.js, Python) hanterar URL-sökning automatiskt. I .NET returneras till exempel VssConnection.GetClient<T>() en klient som redan är bunden till rätt bas-URL.

Om du inte använder ett klientbibliotek:

Leta reda på resursområdes-ID:t för det API du behöver i resursområdes-ID-tabellen. Områdesnamnet brukar visas efter /_apis/ i rutten. Till exempel /_apis/release/definitions tillhör området release (aaaabbbb-0000-cccc-1111-dddd2222eeee).

Anropa REST-API:et för resursområden på organisationsnivå med det ID:t:

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

Använd fältet locationUrl från svaret som bas-URL. I det här exemplet är versionshanteringens bas-URL https://vsrm.dev.azure.com/Fabrikam.

Inga autentiseringsuppgifter krävs för REST-API:et för resursområden.

Exempel: Anropa Releases REST API:et från en pipeline-uppgift

Den här pipeline-aktiviteten bestämmer korrekt bas-URL för Releases REST API:et med hjälp av organisations-URL:en från SYSTEM_TEAMFOUNDATIONCOLLECTIONURI miljövariabeln.

Anmärkning

Resursområdes-ID:n är fasta och kan bäddas in på ett säkert sätt i aktiviteter och annan logik.

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

Resursområde-ID

I följande tabell visas ID:t för vanliga resursområden. Resursområdes-ID:erna är fasta och konsekventa i alla Azure DevOps Services-organisationer.

Resursområdes-ID	Namn
0d55247a-1c47-4462-9b1f-5e2125590ee6	konto
5D6898BB-45EC-463F-95F9-54D49C71752E	bygga
79BEA8F8-C898-4965-8C51-8BBC3966FAA8	samling
79134c72-4a58-4b42-976c-04e7115f32bf	kärna
31C84E0A-3ECE-48FD-A29D-100849AF99BA	kontrollpanel
A0848FA1-3593-4AEC-949C-694C73F4C4CE	delegerad autentisering
6823169A-2419-4015-B2FD-6FD6F026CA00	diskussion
A85B8835-C1A1-4AAC-AE97-1C3D0BA72DBD	distribuerad uppgift
7BF94C77-0CE1-44E5-A0F3-263E4EBBF327	droppe/släppa/tappa
6c2b0933-3600-42ae-bf8b-93d4f7e83594	extensionManagement
67349c8b-6425-42f2-97b6-0843cb037473	favorit
4E080C62-FA21-4FBC-8FEF-2A10A2B38049	Git
4E40F190-2E3F-4D9F-8331-C7788E833080	graf
68ddce18-2501-45f1-a17b-7931a9922690	medlemsrättighetshantering
b3be7473-68ea-4a81-bfc7-9530baaa19ad	NuGet (på engelska)
4c83cfc1-f33a-477e-a789-29d38ffca52e	npm
45FB9450-A28D-476D-9B0F-FB4AEDDFF73	paket
7AB4E64E-C4D8-4F50-AE73-5EF2E21642A5	emballage
2e0bf237-8973-4ec9-a581-9c3d679d1776	Rörledningar
fb13a388-40dd-4a04-b530-013a739c72ef	politik
8ccfef3d-2b87-4e99-8ccb-66e343d2daa8	profil
aaaabbbb-0000-cccc-1111-dddd2222eeee	släppa
57731FDF-7D72-4678-83DE-F8B31266E429	rapportering
EA48A0A1-269C-42D8-B8AD-DDC8FCDC578	sök
3B95FB80-FDDA-4218-B60E-1052D070AE6B	test
C83EAF52-EDF3-4034-AE11-17D38F25404C	testresultat
8AA40520-446D-40E6-89F6-9C9F9CE44C48	TFVC
970AA69F-E316-4D78-B7B0-B7137E47A22C	användare
5264459E-E5E0-4BD8-B118-0985E68A4EC5	vitsighet
1d4f49f9-02b9-4e26-b826-2cdb6195f2a9	arbete
85f8c7b6-92fe-4ba6-8b6d-fbb67c809341	arbetsuppföljning

Navigera programmatiskt med HostNavigationService

Gränssnittet IHostNavigationService gör det möjligt för tillägg att interagera med den överordnade värdramen. Tillägg kan använda det för att läsa och ange URL-hashen, navigera till URL:er, läsa in sidan igen och hantera frågeparametrar.

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

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

Hash-värde

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

Ladda om och dokumenttitel

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

Frågeparametrar

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

Det fullständiga API:et finns i IHostNavigationService och CommonServiceIds.

Nästa steg

Gör ditt tillägg eller din integrering offentlig

Feedback

Var den här sidan till hjälp?

Last updated on 2026-04-03

Arbeta med URL:er i tillägg och integreringar

Primär URL

Hur den primära URL:en används

URL:er som returneras i REST-API:er

Begäran

Svar

Metodtips

Hämta en organisations URL

Efter organisationsnamn

Begäran

Svar

Efter organisations-ID

Hämta bas-URL:en för ett REST-API

Exempel: Anropa Releases REST API:et från en pipeline-uppgift

Resursområde-ID

Navigera programmatiskt med HostNavigationService

Hash-värde

Navigering och fönster

Ladda om och dokumenttitel

Frågeparametrar

Nästa steg

Feedback

Ytterligare resurser