Trabajar con direcciones URL en extensiones e integraciones

Artikulua
05/30/2023

Azure DevOps Services

Con la introducción de Azure DevOps, ahora se puede acceder a los recursos y las API de la organización a través de cualquiera de las siguientes direcciones URL:

https://dev.azure.com/{organization} (nuevo)
https://{organization}.visualstudio.com (heredado)

Independientemente de cuándo se creó la organización, los usuarios, las herramientas y las integraciones pueden interactuar con las API REST de nivel de organización mediante cualquiera de las direcciones URL. Como desarrollador de una extensión, integración o herramienta que interactúa con Azure DevOps, aprenda a trabajar mejor con las direcciones URL disponibles para el código y las direcciones URL de formulario al llamar a las API REST.

Para obtener más información, consulte la referencia de la API rest.

Dirección URL principal de la organización

Cada organización tiene una dirección URL principal designada que es el nuevo formulario o el formulario heredado. Azure DevOps usa la dirección URL principal para construir direcciones URL en determinados escenarios (siga más detalles). La dirección URL principal predeterminada de una organización viene determinada por cuándo se creó la organización, pero un administrador puede cambiarla:

Cuándo se creó la organización	Dirección URL principal predeterminada
On or after 9/10/2018	Nuevo
Antes del 10/9/2018	Heredado

Cómo se usa la dirección URL principal

La dirección URL principal es la dirección URL base de todas las direcciones URL creadas por Azure DevOps en trabajos en segundo plano y otros escenarios automatizados. Vea los ejemplos siguientes:

Direcciones URL proporcionadas a las tareas de Azure Pipelines a través de variables de entorno (como SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)
Direcciones URL incluidas en cargas de eventos de enlaces de servicio (como direcciones URL en resourceContainers)
Direcciones URL en correo electrónico, Slack, Microsoft Teams y notificaciones similares

Por ejemplo, el siguiente fragmento de código de tarea muestra la dirección URL de la organización proporcionada a la tarea:

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

Si esta tarea se ejecuta en una organización donde la dirección URL principal es el nuevo formulario de dirección URL, la salida es https://dev.azure.com/{organization}. La misma tarea ejecutada en una organización donde la dirección URL principal es la salida del https://{organization}.visualstudio.comformulario de dirección URL heredada.

Por lo tanto, es importante que las tareas y los servicios de Azure Pipelines que reciben eventos de los enlaces de servicio controle ambos formularios de dirección URL.

Direcciones URL devueltas en las API REST

Independientemente de la dirección URL principal de una organización, las direcciones URL devueltas en la respuesta a una llamada API REST usan la misma dirección URL base que la dirección URL solicitante. Esta función garantiza que los clientes que llaman a una API REST mediante una dirección URL heredada continúan recibiendo direcciones URL en el mismo formulario (heredado). Por ejemplo, cuando se llama a la API REST projects mediante una dirección URL heredada, las direcciones URL de la respuesta usan el formato heredado:

Solicitud

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

Response

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

Llamar a la misma API con la nueva dirección URL (https://dev.azure.com/Fabrikam/_apis/projects/MyProject) da como resultado direcciones URL devueltas en el nuevo formulario de dirección URL.

Procedimientos recomendados

Para asegurarse de que la extensión, la herramienta o la integración son resistentes a cambiar los formularios de dirección URL de la organización y a los posibles cambios futuros en la ubicación (dominio) de una API REST:

Suponga que la forma de la dirección URL de la organización puede cambiar con el tiempo.
Evite analizar una dirección URL para construir otra dirección URL.
No suponga que una API REST determinada siempre reside en el mismo dominio.
Evite almacenar direcciones URL en el servicio.
Cuando sea posible, use .NET proporcionado por Microsoft, TypeScript (web), Node.jsy bibliotecas cliente de Python con Azure DevOps.

Cómo obtener la dirección URL de una organización

Con solo el nombre o el identificador de la organización, puede obtener su dirección URL base mediante la API REST de áreas de recursos global (https://dev.azure.com/_apis/resourceAreas). Esta API no requiere autenticación. También proporciona información sobre la ubicación (URL) de la organización y la dirección URL base para las API REST, que pueden residir en dominios diferentes.

Un área de recursos es un grupo de recursos y puntos de conexión de la API REST relacionados. Cada área de recursos tiene un identificador conocido (consulte la tabla siguiente). Cada área de recursos tiene una dirección URL base específica de la organización que se puede usar para formar direcciones URL para las API de ese área de recursos. Por ejemplo, la dirección URL base de las API REST de "compilación" para Fabrikam podría ser https://dev.azure.com/Fabrikam, pero la dirección URL base de las API REST de "administración de versiones" podría ser https://vsrm.dev.azure.com/Fabrikam.

Nota:

La API REST de Áreas de recursos devuelve direcciones URL para la organización en función de la dirección URL principal designada de esa organización.

Con el nombre de la organización

Hay varias maneras de obtener la dirección URL base de una organización con su nombre.

Solicitud

Reemplace por {organizationName} el nombre de la organización, por ejemplo, "Fabrikam". 79134C72-4A58-4B42-976C-04E7115F32BF es el identificador del área de recursos "core", que es donde son recursos importantes como "proyectos".

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

Response

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

locationUrl refleja la dirección URL base de la organización.

La biblioteca cliente de .NET proporcionada por Microsoft (Microsoft.VisualStudio.Services.Client) proporciona una clase auxiliar que llama a la API REST de Áreas de recursos automáticamente y devuelve la dirección URL base de una organización.

Nota:

La VssConnectionHelper clase está disponible en la versión 16.139.0-preview y la versión posterior de la biblioteca cliente.

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

Con el identificador de la organización

Para obtener la dirección URL de una organización mediante su identificador GUID, use el hostId parámetro de consulta en los ejemplos anteriores (en lugar de accountName). Por ejemplo:

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

Obtención de la dirección URL base de una API REST

A partir de la dirección URL de una organización, puede usar la API de REST de áreas de recursos para buscar la dirección URL base correcta para cualquier API rest a la que necesite llamar. Este proceso garantiza que el código sea resistente a la ubicación (dominio) de una API REST que cambia en el futuro y evita una lógica potencialmente frágil.

Nota:

Si usa .NET proporcionado por Microsoft, TypeScript (web), Node.js o biblioteca cliente de Python, la búsqueda de direcciones URL se controla automáticamente. Por ejemplo, en .NET al construir y VssConnection llamar a GetClient<T>, el cliente devuelto está enlazado correctamente a la dirección URL base correcta para las API REST llamadas por este cliente.

Si no usa una biblioteca cliente proporcionada por Microsoft:

Use la tabla siguiente para buscar el identificador del área de recursos de la API REST a la que debe llamar. El nombre del área de recursos suele aparecer después /_apis/ en la ruta de la API REST. Por ejemplo, la /_apis/release/definitions API REST pertenece al release área de recursos, que tiene un identificador de efc2f575-36ef-48e9-b672-0c6fb4a48ac5.
Llame a la API REST de áreas de recursos de nivel de organización ({organizationUrl}/_apis/resourceAreas/{resourceAreaId}?api-version=5.0-preview.1) y pase el identificador del área de recursos. Por ejemplo:
```
GET https://dev.azure.com/Fabrikam/_apis/resourceAreas/efc2f575-36ef-48e9-b672-0c6fb4a48ac5?api-version=5.0-preview.1
```
Use el locationUrl campo de la respuesta JSON como la dirección URL base para llamar a otras API REST para esta área. En este ejemplo, la dirección URL base de Release Management API REST es https://vsrm.dev.azure.com/Fabrikam.

Al igual que la API REST de áreas de recursos globales descritas anteriormente, no se requieren credenciales para llamar a la API REST de áreas de recursos de nivel de organización.

Ejemplo: tarea de canalizaciones que llama a una API REST de versiones de Azure Pipelines

En este ejemplo, una tarea de compilación debe llamar a la API REST de versiones de Azure Pipelines. Forma la dirección URL base correcta para esta llamada a la API REST mediante la dirección URL de la organización (proporcionada en una variable de entorno) y la API REST de áreas de recursos.

Nota:

Los identificadores de área de recursos son fijos y se pueden insertar de forma segura en tareas y otra lógica.

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

Identificadores de área de recursos (referencia)

En esta tabla se muestran los identificadores de las áreas de recursos comunes. Consulte la sección anterior para obtener más información sobre cómo usar esta tabla.

Nota:

Los identificadores de área de recursos son fijos y son coherentes en todas las organizaciones de Azure DevOps Services.

Identificador del área de recursos	Nombre
0d55247a-1c47-4462-9b1f-5e2125590ee6	account
5d6898bb-45ec-463f-95f9-54d49c71752e	build
79bea8f8-c898-4965-8c51-8bbc3966faa8	collection
79134c72-4a58-4b42-976c-04e7115f32bf	core
31c84e0a-3ece-48fd-a29d-100849af99ba	dashboard
a0848fa1-3593-4aec-949c-694c73f4c4ce	delegatedAuth
6823169a-2419-4015-b2fd-6fd6f026ca00	debate
a85b8835-c1a1-4aac-ae97-1c3d0ba72dbd	distributedtask
7bf94c77-0ce1-44e5-a0f3-263e4ebbf327	drop
6c2b0933-3600-42ae-bf8b-93d4f7e83594	extensionManagement
67349c8b-6425-42f2-97b6-0843cb037473	Favorito
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	paquete
7ab4e64e-c4d8-4f50-ae73-5ef2e2e21642a5	empaquetado
2e0bf237-8973-4ec9-a581-9c3d679d1776	pipelines
fb13a388-40dd-4a04-b530-013a739c72ef	policy
8ccfef3d-2b87-4e99-8ccb-66e343d2daa8	perfile
efc2f575-36ef-48e9-b672-0c6fb4a48ac5	release
57731fdf-7d72-4678-83de-f8b31266e429	informes
ea48a0a1-269c-42d8-b8ad-ddc8fcdcf578	paquetes Bower
3b95fb80-fdda-4218-b60e-1052d070ae6b	test
c83eaf52-edf3-4034-ae11-17d38f25404c	testresults
8aa40520-446d-40e6-89f6-9c9f9ce44c48	tfvc
970aa69f-e316-4d78-b7b0-b7137e47a22c	usuario
5264459e-e5e0-4bd8-b118-0985e68a4ec5	Ingenio
1d4f49f9-02b9-4e26-b826-2cdb6195f2a9	work
85f8c7b6-92fe-4ba6-8b6d-fbb67c809341	worktracking

Pasos siguientes

Hacer pública la extensión o la integración

Partekatu honen bidez:

Trabajar con direcciones URL en extensiones e integraciones

Dirección URL principal de la organización

Cómo se usa la dirección URL principal

Direcciones URL devueltas en las API REST

Solicitud

Response

Procedimientos recomendados

Cómo obtener la dirección URL de una organización

Con el nombre de la organización

Solicitud

Response

Con el identificador de la organización

Obtención de la dirección URL base de una API REST

Ejemplo: tarea de canalizaciones que llama a una API REST de versiones de Azure Pipelines

Identificadores de área de recursos (referencia)

Pasos siguientes

Oharrak

Baliabide gehigarriak