Trabaje con direcciones URL en extensiones e integraciones

Servicios de Azure DevOps | Azure DevOps Server | Azure DevOps Server 2022

Puede acceder a los recursos y LAS API de la organización de Azure DevOps mediante dos formularios de dirección URL:

Formulario de dirección URL	Ejemplo
Nuevo	`https://dev.azure.com/{organization}`
Legado	`https://{organization}.visualstudio.com`

Las API REST de nivel de organización aceptan cualquier formulario de dirección URL, independientemente de cuándo haya creado la organización. Para más información, consulte la referencia de la API REST de Azure DevOps Services.

Dirección URL principal

Cada organización tiene una dirección URL principal designada en el formulario nuevo o heredado. Un administrador puede cambiar la dirección URL principal. El valor predeterminado se basa en cuando creó la organización:

Creado	Dirección URL principal predeterminada
En o después del 10 de septiembre de 2018	Nuevo
Antes del 10 de septiembre de 2018	Legado

Cómo se usa la dirección URL principal

Azure DevOps usa la dirección URL principal como base para todas las direcciones URL que construye en trabajos en segundo plano y escenarios automatizados, entre los que se incluyen:

Variables de entorno de tareas de canalización (como SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)
Cargas de eventos de enlaces de servicio (como direcciones URL en resourceContainers)
Correo electrónico, Slack, Microsoft Teams y notificaciones similares

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

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

La salida depende del formulario de dirección URL principal de la organización, ya sea https://dev.azure.com/{organization} o https://{organization}.visualstudio.com. Asegúrese de que las tareas de las canalizaciones y los consumidores de ganchos de servicio gestionen ambas formas de 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 a la API REST usan la misma dirección URL base que la dirección URL de solicitud. Esta función garantiza que los clientes que llaman a una API REST mediante una dirección URL heredada sigan recibiendo direcciones URL en el mismo formato (heredado). Por ejemplo, cuando se llama a la API REST de proyectos 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

Respuesta

{
  "id": "e4e4e4e4-ffff-aaaa-bbbb-c5c5c5c5c5c5",
  "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 mantener la extensión, la herramienta o la integración resistentes a los cambios de dirección URL:

No suponga una forma fija de URL de la organización. Puede cambiar con el tiempo.
No analice ni almacene direcciones URL para construir otras direcciones URL.
No suponga que una API REST siempre reside en el mismo dominio.
Use las bibliotecas cliente proporcionadas por Microsoft (.NET, Node.js, Python) siempre que sea posible, ya que controlan la resolución de direcciones URL automáticamente.

Obtener la dirección URL de una organización

Puede resolver la dirección URL base de una organización a partir de su nombre o identificador mediante la API REST de áreas de recursos global (https://dev.azure.com/_apis/resourceAreas). Esta API no requiere autenticación.

Un área de recursos es un grupo de puntos de conexión de API REST relacionados identificados por un GUID fijo. Cada área de recursos puede tener una dirección URL base diferente para cada organización. Por ejemplo, las API de compilación de Fabrikam pueden usar https://dev.azure.com/Fabrikam, mientras que las API de administración de versiones usan https://vsrm.dev.azure.com/Fabrikam.

Nota:

La API REST de Áreas de Recursos devuelve direcciones URL basadas en la dirección URL principal designada de la organización.

Por nombre de la organización

Reemplace por {organizationName} el nombre de la organización. El GUID 79134C72-4A58-4B42-976C-04E7115F32BF identifica el área de recursos principal , que contiene recursos como proyectos.

Solicitud

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

Respuesta

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

El locationUrl campo contiene la dirección URL base de la organización.

La biblioteca cliente de .NET proporciona VssConnectionHelper, que llama a la API REST de áreas de recursos y devuelve la dirección URL base de la organización.

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

Por identificador de organización

Para resolver la dirección URL por GUID de la organización en lugar del nombre, use el hostId parámetro de consulta (en lugar de accountName):

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

Use la API REST de áreas de recursos de nivel de organización para buscar la dirección URL base correcta para cualquier API REST. Este enfoque mantiene el código resistente cuando cambian los dominios de API.

Nota:

Las bibliotecas cliente proporcionadas por Microsoft (.NET, TypeScript, Node.js, Python) controlan automáticamente la búsqueda de direcciones URL. Por ejemplo, VssConnection.GetClient<T>() en .NET devuelve un cliente que ya está enlazado a la dirección URL base correcta.

Si no usa una biblioteca cliente:

Busque el identificador del área de recursos de la API que necesita en la tabla de identificadores de área de recursos. El nombre del área normalmente aparece después de /_apis/ en la ruta. Por ejemplo, /_apis/release/definitions pertenece al release área (aaaabbbb-0000-cccc-1111-dddd2222eeee).

Llame a la API REST de áreas de recursos de nivel de organización con ese identificador:

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

Use el locationUrl campo de la respuesta como dirección URL base. En este ejemplo, la dirección URL base de Release Management es https://vsrm.dev.azure.com/Fabrikam.

No se requieren credenciales para la API REST de áreas de recursos.

Ejemplo: Llamar a la API REST Releases desde una tarea de canalización

Esta tarea de canalización resuelve la dirección URL base correcta para la API REST de Releases mediante la variable de entorno SYSTEM_TEAMFOUNDATIONCOLLECTIONURI de la dirección URL de la organización.

Nota:

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

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

Identificadores de área de recursos

En la tabla siguiente se enumeran los identificadores de las áreas de recursos comunes. Los identificadores de área de recursos son fijos y 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	Construir
79bea8f8-c898-4965-8c51-8bbc3966faa8	colección
79134c72-4a58-4b42-976c-04e7115f32bf	núcleo
31C84E0A-3ECE-48FD-A29D-100849AF99BA	panel
A0848FA1-3593-4AEC-949C-694C73F4C4CE	autenticación delegada
6823169A-2419-4015-B2FD-6FD6F026CA00	discusión
A85B8835-C1A1-4AAC-AE97-1C3D0BA72DBD	Tarea distribuida
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	Gestión de Derechos de Miembros
B3BE7473-68EA-4A81-BFC7-9530BAAA19AD	NuGet
4C83CFC1-F33A-477E-A789-29D38FFCA52E	npm
45fb9450-a28d-476d-9b0f-fb4aedddff73	paquete
7ab4e64e-c4d8-4f50-ae73-5ef2e2e21642a5	embalaje
2e0bf237-8973-4ec9-a581-9c3d679d1776	canalizaciones
FB13A388-40DD-4A04-B530-013A739C72EF	política
8ccfef3d-2b87-4e99-8ccb-66e343d2daa8	perfil
aaaabbbb-0000-cccc-1111-dddd2222eeee	release
57731fdf-7d72-4678-83de-f8b31266e429	Informes
EA48A0A1-269C-42D8-B8AD-DDC8FCDCF578	búsqueda
3B95FB80-FDDA-4218-B60E-1052D070AE6B	test
C83EAF52-EDF3-4034-AE11-17D38F25404C	resultados de prueba
8aa40520-446d-40e6-89f6-9c9f9ce44c48	TFVC
970aa69f-e316-4d78-b7b0-b7137e47a22c	usuario
5264459e-e5e0-4bd8-b118-0985e68a4ec5	Ingenio
1d4f49f9-02b9-4e26-b826-2cdb6195f2a9	trabajo
85f8c7b6-92fe-4ba6-8b6d-fbb67c809341	seguimiento de trabajo

Navegación mediante programación con HostNavigationService

La IHostNavigationService interfaz permite que las extensiones interactúen con el marco de host primario. Las extensiones pueden usarla para leer y establecer el hash de dirección URL, navegar a direcciones URL, volver a cargar la página y administrar parámetros de consulta.

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

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

Valor del código 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");

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

Recarga y título del documento

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

Parámetros de consulta

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

Para obtener la API completa, consulte IHostNavigationService y CommonServiceIds.

Paso siguiente

Hacer que la extensión o la integración sean públicas

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-05-08

Trabaje con direcciones URL en extensiones e integraciones

Dirección URL principal

Cómo se usa la dirección URL principal

Direcciones URL devueltas en las API REST

Solicitud

Respuesta

procedimientos recomendados

Obtener la dirección URL de una organización

Por nombre de la organización

Solicitud

Respuesta

Por identificador de organización

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

Ejemplo: Llamar a la API REST Releases desde una tarea de canalización

Identificadores de área de recursos

Navegación mediante programación con HostNavigationService

Valor del código hash

Navegación y ventanas

Recarga y título del documento

Parámetros de consulta

Paso siguiente

Comentarios

Recursos adicionales