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

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

  • Cikk

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.

Az API-k egy gyakori mintát követnek, például az alábbi példában.

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 instance esetében ez és collection így is van dev.azure.com/{organization} DefaultCollection, így a minta az alábbi 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 EGY HTTP-fejlécen keresztül szeretné megadni a személyes hozzáférési jogkivonatot (PAT), először base64-sztringgé kell konvertálnia. Az alábbi példa bemutatja, hogyan konvertálható Base64-be C# használatával. Az eredményül kapott sztring ezután megadható HTTP-fejlécként a formátumban.

Authorization: Basic BASE64PATSTRING

Az alábbi példa a C#-ot mutatja be a HttpClient osztály használatával.

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

A legtöbb mintánk PAT-t használ, mivel ez egy kompakt példa a szolgáltatással való hitelesítésre. Az Azure DevOps Serviceshez azonban különböző hitelesítési mechanizmusok érhetők el, például a Microsoft Authentication Library (MSAL), az OAuth és a munkamenet-jogkivonatok esetében. További információ: Hitelesítési útmutató, amely segít meghatározni, hogy melyik felel meg a legjobban a forgatókönyvnek.

Azure DevOps Server

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

Az alapértelmezett gyűjtemény, DefaultCollectionde 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, amelyekhez PAT-t kell létrehozni.

Válaszok

Ehhez hasonló választ kell kapnia.

{
    "value": [
        {
            "id": "eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "name": "Fabrikam-Fiber-TFVC",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1",
            "description": "TeamFoundationVersionControlprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "66df9be7-3586-467b-9c5f-425b29afedfd",
                "name": "Fabrikam-Fiber-TFVCTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/eb6e4656-77fc-42a1-9181-4c6d8e9da5d1/teams/66df9be7-3586-467b-9c5f-425b29afedfd"
            }
        },
        {
            "id": "6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "name": "Fabrikam-Fiber-Git",
            "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c",
            "description": "Gitprojects",
            "collection": {
                "id": "d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "name": "DefaultCollection",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projectCollections/d81542e4-cdfa-4333-b082-1ae2d6c3ad16",
                "collectionUrl": "https: //dev.azure.com/fabrikam-fiber-inc"
            },
            "defaultTeam": {
                "id": "8bd35c5e-30bb-4834-a0c4-d576ce1b8df7",
                "name": "Fabrikam-Fiber-GitTeam",
                "url": "https: //dev.azure.com/fabrikam-fiber-inc/_apis/projects/6ce954b1-ce1f-45d1-b94d-e6bf2464ba2c/teams/8bd35c5e-30bb-4834-a0c4-d576ce1b8df7"
            }
        }
    ],
    "count": 2
}

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

Most áttekintheti az adott API-területeket , például a munkaelemek nyomon követését 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-parancsok

Parancs Használt...
KAP Erőforrás vagy erőforráslista lekérése
POST Erőforrás létrehozása, Erőforrások listájának lekérése speciálisabb lekérdezéssel
PUT 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örlés... 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 igét egy fejléccel a metódus felülbírálásához. 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álasztö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álasztörzs. 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 sikertelen. 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 lekéréses kérelmet próbál elküldeni, és már van lekéréses kérelem a véglegesítésekhez, 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 a nem tartományból dev.azure.com/* kiszolgált JavaScript-kódot, hogy 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 myPatToken személyes hozzáférési jogkivonatra)

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ányelvek

  • Adja meg az API-verziót minden kéréssel (kötelező).
  • 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átum használatával: 1.0-preview.1, 1.0-preview.2. Miután az API megjelent (például 1.0 verziószámmal), az előzetes verziója (1.0-preview) elavulttá válik, és 12 hét elteltével inaktiválható.
  • Frissítsen az API kiadott verziójára. Az előzetes verziójú API inaktiválása után a verziót meghatározó -preview 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 a REST API verziószámozása és a támogatott verziók című témakörben talál.