Megosztás a következőn keresztül:

A REST API-k használatának első lépései

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Az alkalmazás integrálása az Azure DevOpsszal a cikkben található REST API-k használatával. Ezek az API-k lehetővé teszik a szolgáltatások programozott használatát, így automatizálhatja a munkafolyamatokat, integrálható más rendszerekkel, és bővítheti az Azure DevOps képességeit.

Az API-k egy gyakori mintát követnek, ahogyan az alábbi példában látható:

VERB https://{instance}/{collection}/{team-project}/_apis/{area}/{resource}?api-version={version}

Tipp

Az API-k fejlődésével azt javasoljuk, hogy minden kéréshez mellékeljen egy API-verziót. Ez a gyakorlat segíthet elkerülni az API váratlan változásait, amelyek megszakadhatnak.

Azure DevOps Services

Az Azure DevOps Services esetében instancedev.azure.com/{organization} és collectionDefaultCollection, így a minta a következő példához hasonlóan néz ki:

VERB https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version={version}

Az alábbi példa bemutatja, hogyan szerezheti be a szervezetek projektjeinek listáját:

curl -u {username}:{personalaccesstoken} https://dev.azure.com/{organization}/_apis/projects?api-version=2.0

Ha a személyes hozzáférési token (PAT) egy HTTP-fejlécen keresztül szeretné megadni, először egy kettőspontot kell hozzáadni a PAT-hez. Ezután alakítsa át a kettőspont és a PAT összefűzését Base64 karakterlánccá. Az alábbi példa bemutatja, hogyan konvertálható Base64-be C# használatával. Az eredményül kapott sztring ezután HTTP-fejlécként is megadható a következő formátumban:

Authorization: Basic BASE64COLONANDPATSTRING

Megjegyzés

A hitelesítési hibák elkerülése érdekében vegye fel a kettőspontot a PAT elé.

Az alábbi példa a C#-ot mutatja be a HttpClient osztállyal.

public static async void GetProjects()
{
    try
    {
        var personalaccesstoken = "PAT_FROM_WEBSITE";

        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Accept.Add(
                new System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json"));

            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic",
                Convert.ToBase64String(
                    System.Text.ASCIIEncoding.ASCII.GetBytes(
                        string.Format("{0}:{1}", "", personalaccesstoken))));

            using (HttpResponseMessage response = client.GetAsync(
                        "https://dev.azure.com/{organization}/_apis/projects").Result)
            {
                response.EnsureSuccessStatusCode();
                string responseBody = await response.Content.ReadAsStringAsync();
                Console.WriteLine(responseBody);
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex.ToString());
    }
}

Fontos

Bár számos példában személyes hozzáférési jogkivonatokat (PAT-okat) használunk az egyszerűség kedvéért, nem javasoljuk a használatukat éles alkalmazásokhoz. Ehelyett fontolja meg a biztonságosabb hitelesítési mechanizmusok használatát. További információ: Hitelesítési útmutató.

Azure DevOps Server

Az Azure DevOps Server esetében instance{server:port} van. A nem SSL-kapcsolat alapértelmezett portja a 8080.

Az alapértelmezett gyűjtemény DefaultCollection, de bármilyen gyűjteményt használhat.

Az alábbi módszerrel szerezheti be a projektek listáját az Azure DevOps Serverről az alapértelmezett port és gyűjtemény ssl-alapú használatával:

curl -u {username}:{personalaccesstoken} https://{server}/DefaultCollection/_apis/projects?api-version=2.0

Ha ugyanazt a listát szeretné lekérni egy nem SSL-kapcsolaton keresztül:

curl -u {username}:{personalaccesstoken} http://{server}:8080/DefaultCollection/_apis/projects?api-version=2.0

Ezek a példák PAT-okat használnak, amelyek megkövetelik, hogy létrehozz egy PAT-ot.

Válaszok

A következő példához hasonló választ kell kapnia:

{
    "value": [
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
            }
        },
        {
            "id": "00000000-0000-0000-0000-000000000000",
            "name": "Fabrikam-Fiber-Git",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000",
            "description": "Gitprojects",
            "collection": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/00000000-0000-0000-0000-000000000000",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "00000000-0000-0000-0000-000000000000",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/00000000-0000-0000-0000-000000000000/teams/00000000-0000-0000-0000-000000000000"
            }
        }
    ],
    "count": 2
}

A válasz JSON, amely általában a REST API-kból származik, bár van néhány kivétel, például Git-blobok.

Most áttekintheti az adott API-területeket, például a munkaelem-követést vagy a Gitet, és elérheti a szükséges erőforrásokat. További információt az ezekben az API-kban használt általános mintákról olvashat.

HTTP-műveletek

Ige Felhasználva...
SZEREZZE MEG Erőforrás vagy erőforráslista lekérése
poszt Erőforrás létrehozása, Erőforrások listájának lekérése speciálisabb lekérdezéssel
Helyezze Erőforrás létrehozása, ha nem létezik, vagy ha igen, frissítse
javítás Erőforrás frissítése
töröl Erőforrások törlése

Fejlécek kérése és tartalom kérése

Amikor kéréstörzset ad meg (általában a POST, a PUT és a PATCH igével), a törzset leíró kérésfejléceket is tartalmaznia kell. Például

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/build-release/requests

Content-Type: application/json

{
   "definition": {
      "id": 3
   },
   "reason": "Manual",
   "priority": "Normal"
}

HTTP-metódus felülbírálása

Egyes webes proxyk csak a GET és a POST HTTP-igéket támogatják, a modernEBB HTTP-parancsokat azonban nem, például a PATCH és a DELETE parancsokat. Ha a hívások áthaladhatnak ezen proxyk egyikén, POST metódussal küldheti el a tényleges műveletet egy fejléc segítségével, amely felülbírálja a metódust. Előfordulhat például, hogy frissíteni szeretne egy munkaelemet (PATCH _apis/wit/workitems/3), de előfordulhat, hogy olyan proxyn kell keresztülmennie, amely csak a GET vagy a POST szolgáltatást teszi lehetővé. A megfelelő igét (ebben az esetben a PATCH-et) átadhatja HTTP-kérelem fejlécparaméterként, és a POST-ot használhatja tényleges HTTP-metódusként.

POST https://dev.azure.com/fabrikam-fiber-inc/_apis/wit/workitems/3

X-HTTP-Method-Override: PATCH

{
   (PATCH request body)
}

Válaszkódok

Válasz Jegyzetek
200 Siker, és van egy válasz törzs.
201 Siker az erőforrások létrehozásakor. Egyes API-k 200 értéket adnak vissza egy erőforrás sikeres létrehozásakor. A biztonság érdekében tekintse meg a használt API dokumentációját.
204 Siker, és nincs válasz tartalom. Ez a válasz például akkor jelenik meg, ha töröl egy erőforrást.
400 Az URL-címben vagy a kérelem törzsében lévő paraméterek érvénytelenek.
401 A hitelesítés nem sikerült. Ezt a választ gyakran egy hiányzó vagy hibásan formázott engedélyezési fejléc okozza.
403 A hitelesített felhasználónak nincs engedélye a művelet végrehajtására.
404 Az erőforrás nem létezik, vagy a hitelesített felhasználó nem rendelkezik engedéllyel a létezésének megtekintéséhez.
409 Ütközés van a kérés és a kiszolgálón lévő adatok állapota között. Ha például megpróbál elküldeni egy pull kérést, de már létezik egy pull kérés a commit-ekhez, a válaszkód 409.

Eltérő eredetű erőforrások megosztása (CORS)

Az Azure DevOps Services támogatja a CORS-t, amely lehetővé teszi, hogy a nem dev.azure.com/* tartományból kiszolgált JavaScript-kód Ajax-kéréseket küldjön az Azure DevOps Services REST API-knak. Minden kérésnek meg kell adnia a hitelesítő adatokat (a PAT-k és az OAuth hozzáférési jogkivonatok egyaránt támogatottak). Példa:

    $( document ).ready(function() {
        $.ajax({
            url: 'https://dev.azure.com/fabrikam/_apis/projects?api-version=1.0',
            dataType: 'json',
            headers: {
                'Authorization': 'Basic ' + btoa("" + ":" + myPatToken)
            }
        }).done(function( results ) {
            console.log( results.value[0].id + " " + results.value[0].name );
        });
    });

Cserélje le a myPatToken egy PAT-ra.

Verziókezelés

Az Azure DevOps REST API-k verziószáma biztosítja, hogy az alkalmazások és szolgáltatások továbbra is működjenek az API-k fejlődésével.

Iránymutatások

  • Adja meg az API-verziót minden kéréssel (szükséges).
  • Az API-verziók formázása a következő módon: {major}.{minor}-{stage}.{resource-version}. Például: 1.0, 1.1, 1.2-preview, 2.0.
  • Adja meg az API egy adott verzióját, amikor előzetes verzióban van, a következő verzióformátummal: 1.0-preview.1, 1.0-preview.2. Az API kiadása (például 1.0) után az előzetes verzió (1.0-preview) elavult, és 12 hét után inaktiválható.
  • Frissítsen az API kiadott verziójára. Az előzetes verziójú API inaktiválása után a -preview verziót meghatározó kérések elutasításra kerülnek.

Használat

Adja meg az API-verziót a HTTP-kérés fejlécében vagy URL-lekérdezési paraméterként.

HTTP-kérelem fejléce:

Accept: application/json;api-version=1.0

Lekérdezési paraméter:

GET https://dev.azure.com/{organization}/_apis/{area}/{resource}?api-version=1.0

Támogatott verziók

A támogatott verziókról további információt REST API-verziószámozás, támogatott verziókcímű témakörben talál.