Werken met URL's in extensies en integraties

Artikel
07/17/2024

Azure DevOps Services

Met de introductie van Azure DevOps zijn organisatieresources en API's nu toegankelijk via een van de volgende URL's:

https://dev.azure.com/{organization} (nieuw)
https://{organization}.visualstudio.com (verouderd)

Ongeacht wanneer de organisatie is gemaakt, kunnen gebruikers, hulpprogramma's en integraties communiceren met REST API's op organisatieniveau met behulp van beide URL's. Als ontwikkelaar van een extensie, integratie of hulpprogramma dat communiceert met Azure DevOps, leert u hoe u het beste kunt werken met URL's die beschikbaar zijn voor uw code en formulier-URL's wanneer u REST API's aanroept.

Zie de REST API-verwijzing voor meer informatie.

Primaire URL van organisatie

Elke organisatie heeft een aangewezen primaire URL die het nieuwe formulier of het verouderde formulier is. De primaire URL wordt gebruikt door Azure DevOps voor het maken van URL's in bepaalde scenario's (meer details volgen). De standaard primaire URL voor een organisatie wordt bepaald door het moment waarop de organisatie is gemaakt, maar kan worden gewijzigd door een beheerder:

Toen de organisatie werd gemaakt	Standaard primaire URL
Op of na 10-9-2018	Nieuw
Voor 10-9-2018	Legacy

Hoe de primaire URL wordt gebruikt

De primaire URL is de basis-URL voor alle URL's die door Azure DevOps zijn samengesteld in achtergrondtaken en andere geautomatiseerde scenario's. Zie de volgende voorbeelden.

URL's die worden geleverd aan Azure Pipelines-taken via omgevingsvariabelen (zoals SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)
URL's die zijn opgenomen in nettoladingen van servicehookgebeurtenissen (zoals URL's in resourceContainers)
URL's in e-mail, Slack, Microsoft Teams en soortgelijke meldingen

In het volgende taakfragment wordt bijvoorbeeld de organisatie-URL weergegeven die aan de taak is opgegeven:

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

Als deze taak wordt uitgevoerd in een organisatie waar de primaire URL het nieuwe URL-formulier is, is https://dev.azure.com/{organization}de uitvoer . Dezelfde taak die wordt uitgevoerd op een organisatie waarbij de primaire URL de verouderde URL-formulier is, wordt uitgevoerd https://{organization}.visualstudio.com.

Het is daarom belangrijk dat Azure Pipelines-taken en -services die gebeurtenissen van servicehook ontvangen beide URL-formulieren verwerken.

URL's die worden geretourneerd in REST API's

Ongeacht de primaire URL van een organisatie, gebruiken URL's die worden geretourneerd in het antwoord op een REST API-aanroep dezelfde basis-URL als de aanvragende URL. Deze functie zorgt ervoor dat clients die een REST API aanroepen met behulp van een verouderde URL, URL's in dezelfde (verouderde) vorm terughalen. Wanneer de Projects REST API bijvoorbeeld wordt aangeroepen met behulp van een verouderde URL, gebruiken URL's in het antwoord de verouderde vorm:

Aanvraag

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

Antwoord

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

Het aanroepen van dezelfde API met behulp van de nieuwe URL (https://dev.azure.com/Fabrikam/_apis/projects/MyProject) resulteert in URL's die worden geretourneerd in het nieuwe URL-formulier.

Aanbevolen procedures

Om ervoor te zorgen dat uw extensie, hulpprogramma of integratie bestand is tegen veranderende formulieren voor organisatie-URL's en mogelijke toekomstige wijzigingen in de locatie (domein) van een REST API:

Stel dat de vorm van de organisatie-URL na verloop van tijd kan veranderen.
Vermijd het parseren van een URL om een andere URL te maken.
Ga er niet van uit dat een bepaalde REST API zich altijd in hetzelfde domein bevindt.
Vermijd het opslaan van URL's in uw service.
Gebruik indien mogelijk door Microsoft geleverde .NET-, TypeScript- Node.js- en Python-clientbibliotheken met Azure DevOps.

De URL van een organisatie ophalen

Met alleen de naam of id van de organisatie kunt u de basis-URL ophalen met behulp van de globale REST API voor resourcegebieden (https://dev.azure.com/_apis/resourceAreas). Voor deze API is geen verificatie vereist. Het biedt ook informatie over de locatie (URL) van de organisatie en de basis-URL voor REST API's, die zich in verschillende domeinen kunnen bevinden.

Een resourcegebied is een groep gerelateerde REST API-resources en -eindpunten. Elk resourcegebied heeft een bekende id (zie de volgende tabel). Elk resourcegebied heeft een organisatiespecifieke basis-URL die kan worden gebruikt om URL's te maken voor API's in dat resourcegebied. De basis-URL voor 'build' REST API's voor Fabrikam kan bijvoorbeeld zijn https://dev.azure.com/Fabrikam, maar de basis-URL voor 'releasebeheer' REST API's kan zijn https://vsrm.dev.azure.com/Fabrikam.

Notitie

De REST API voor resourcegebieden retourneert URL's voor de organisatie op basis van de aangewezen primaire URL van die organisatie.

Met de naam van de organisatie

Er zijn een aantal manieren om de basis-URL voor een organisatie op te halen met behulp van de naam.

Aanvraag

Vervang door {organizationName} de naam van de organisatie, bijvoorbeeld Fabrikam. 79134C72-4A58-4B42-976C-04E7115F32BF is de id voor het 'kernresourcegebied', waar belangrijke resources zoals 'projecten' zich bevinden.

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

Antwoord

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

De locationUrl weerspiegelt de basis-URL van de organisatie.

De door Microsoft geleverde .NET-clientbibliotheek (Microsoft.VisualStudio.Services.Client) biedt een helperklasse die de REST API voor resourcegebieden voor u aanroept en de basis-URL voor een organisatie retourneert.

Notitie

De VssConnectionHelper klasse is beschikbaar in versie 16.139.0-preview en latere versie van de clientbibliotheek.

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

Met de organisatie-id

Als u de URL voor een organisatie wilt ophalen met behulp van de GUID-id, gebruikt u de hostId queryparameter in de vorige voorbeelden (in plaats van accountName). Bijvoorbeeld:

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

De basis-URL voor een REST API ophalen

Vanaf de URL van een organisatie kunt u de REST API voor resourcegebieden gebruiken om de juiste basis-URL op te zoeken voor elke REST API die u wilt aanroepen. Dit proces zorgt ervoor dat uw code bestand is tegen de locatie (domein) van een REST API die in de toekomst wordt gewijzigd en dat mogelijk broze logica wordt vermeden.

Notitie

Als u de door Microsoft geleverde clientbibliotheek voor .NET, TypeScript (web), Node.js of Python gebruikt, wordt het opzoeken van URL's voor u afgehandeld. Wanneer u bijvoorbeeld in .NET een VssConnection maakt en aanroept GetClient<T>, is de geretourneerde client correct gebonden aan de juiste basis-URL voor de REST API's die door deze client worden aangeroepen.

Als u geen door Microsoft geleverde clientbibliotheek gebruikt:

Gebruik de volgende tabel om de resourcegebied-id te vinden voor de REST API die u moet aanroepen. De naam van het resourcegebied wordt meestal na /_apis/ weergegeven in de REST API-route. De REST API behoort bijvoorbeeld /_apis/release/definitions tot het release resourcegebied, met een id van efc2f575-36ef-48e9-b672-0c6fb4a48ac5.
Roep de REST API voor resourcegebieden op organisatieniveau aan ({organizationUrl}/_apis/resourceAreas/{resourceAreaId}?api-version=5.0-preview.1) en geef de resourcegebied-id door. Bijvoorbeeld:
```
GET https://dev.azure.com/Fabrikam/_apis/resourceAreas/efc2f575-36ef-48e9-b672-0c6fb4a48ac5?api-version=5.0-preview.1
```
Gebruik het locationUrl veld uit het JSON-antwoord als de basis-URL voor het aanroepen van andere REST API's voor dit gebied. In dit voorbeeld is https://vsrm.dev.azure.com/Fabrikamde basis-URL voor RELEASE Management REST API's .

Net als bij de globale REST API voor resourcegebieden die eerder is beschreven, zijn er geen referenties vereist om de REST API voor resourcegebieden op organisatieniveau aan te roepen.

Voorbeeld: Pijplijntaak die een Azure Pipelines aanroept, releases REST API

In dit voorbeeld moet een build-taak de REST API van Azure Pipelines-releases aanroepen. Deze vormt de juiste basis-URL voor deze REST API-aanroep met behulp van de organisatie-URL (opgegeven in een omgevingsvariabele) en de REST API voor resourcegebieden.

Notitie

Resourcegebied-id's staan vast en kunnen veilig worden ingesloten in taken en andere logica.

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

Resourcegebied-id's (verwijzing)

In deze tabel ziet u de id's voor gemeenschappelijke resourcegebieden. Zie de vorige sectie voor meer informatie over het gebruik van deze tabel.

Notitie

Resourcegebied-id's staan vast en zijn consistent in alle organisaties in Azure DevOps Services.

Resourcegebied-id	Naam
0d55247a-1c47-4462-9b1f-5e2125590ee6	account
5d6898bb-45ec-463f-95f9-54d49c71752e	bouwen
79bea8f8-c898-4965-8c51-8bbc3966faa8	verzameling
79134c72-4a58-4b42-976c-04e7115f32bf	Core
31c84e0a-3ece-48fd-a29d-100849af99ba	Dashboard
a0848fa1-3593-4aec-949c-694c73f4c4ce	delegatedAuth
6823169a-2419-4015-b2fd-6fd6f026ca00	discussie
a85b8835-c1a1-4aac-ae97-1c3d0ba72dbd	gedistribueerde taken
7bf94c77-0ce1-44e5-a0f3-263e4ebbf327	drop
6c2b0933-3600-42ae-bf8b-93d4f7e83594	extensionManagement
67349c8b-6425-42f2-97b6-0843cb037473	favoriet
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	pakket
7ab4e64e-c4d8-4f50-ae73-5ef2e21642a5	Verpakking
2e0bf237-8973-4ec9-a581-9c3d679d1776	Pijpleidingen
fb13a388-40dd-4a04-b530-013a739c72ef	policy
8ccfef3d-2b87-4e99-8ccb-66e343d2daa8	profiel
efc2f575-36ef-48e9-b672-0c6fb4a48ac5	Release
57731fdf-7d72-4678-83de-f8b31266e429	rapportering
ea48a0a1-269c-42d8-b8ad-ddc8fcdcf578	zoeken
3b95fb80-fdda-4218-b60e-1052d070ae6b	test
c83eaf52-edf3-4034-ae11-17d38f25404c	testresults
8aa40520-446d-40e6-89f6-9c9f9ce44c48	tfvc
970aa69f-e316-4d78-b7b0-b7137e47a22c	gebruiker
5264459e-e5e0-4bd8-b118-0985e68a4ec5	wit
1d4f49f9-02b9-4e26-b826-2cdb6195f2a9	werk
85f8c7b6-92fe-4ba6-8b6d-fbb67c809341	worktracking

Volgende stappen

Uw extensie of integratie openbaar maken

Delen via

Werken met URL's in extensies en integraties

Primaire URL van organisatie

Hoe de primaire URL wordt gebruikt

URL's die worden geretourneerd in REST API's

Aanvraag

Antwoord

Aanbevolen procedures

De URL van een organisatie ophalen

Met de naam van de organisatie

Aanvraag

Antwoord

Met de organisatie-id

De basis-URL voor een REST API ophalen

Voorbeeld: Pijplijntaak die een Azure Pipelines aanroept, releases REST API

Resourcegebied-id's (verwijzing)

Volgende stappen

Feedback

Aanvullende resources