Vyvolání funkcí Azure Nebo kontrol rozhraní REST API

Volání funkce Azure Nebo kontroly rozhraní REST API umožňuje napsat kód, který rozhoduje, jestli má konkrétní fáze kanálu povolený přístup k chráněnému prostředku nebo ne. Tyto kontroly se můžou spouštět ve dvou režimech:

• Asynchronní (doporučeno): Režim nabízených oznámení, ve kterém Azure DevOps čeká na implementaci služby Azure Functions nebo rozhraní REST API, která se bude volat zpět do Azure DevOps s rozhodovacím rozhodnutím o fázovém přístupu
• Synchronní: režim dotazování, ve kterém Azure DevOps pravidelně volá funkci Azure Nebo rozhraní REST API, aby získalo rozhodnutí o fázovém přístupu

Ve zbývající části tohoto průvodce odkazujeme na funkci Azure Functions / REST API kontroly jednoduše jako kontroly.

Doporučený způsob použití kontrol je v asynchronním režimu. Tento režim nabízí nejvyšší úroveň kontroly nad logikou kontroly, usnadňuje důvod k tomu, v jakém stavu je systém, a oddělí Azure Pipelines od implementace kontrol a zajistí nejlepší škálovatelnost. Všechny synchronní kontroly je možné implementovat pomocí režimu asynchronních kontrol.

Asynchronní kontroly

Azure DevOps v asynchronním režimu volá funkci Azure Nebo rozhraní REST API a čeká na zpětné volání s rozhodnutím o přístupu k prostředkům. Během čekací doby neexistuje žádné otevřené připojení HTTP mezi Azure DevOps a implementací kontroly.

Zbytek této části popisuje kontroly funkcí Azure, ale pokud není uvedeno jinak, pokyny platí i pro vyvolání kontrol rozhraní REST API.

Doporučená implementace asynchronních kontrol

Doporučený asynchronní režim má dva komunikační kroky:

1. Doručte datovou část kontroly. Azure Pipelines volá funkci Azure Functions nebo rozhraní REST API http pouze k doručení datové části kontroly, a ne k přijetí rozhodnutí na místě. Vaše funkce by měla pouze potvrdit přijetí informací a ukončit připojení HTTP s Azure DevOps. Implementace kontroly by měla zpracovat požadavek HTTP do 3 sekund.
2. Zajištění rozhodnutí o přístupu prostřednictvím zpětného volání Kontrola by měla běžet asynchronně, vyhodnotit podmínku potřebnou pro přístup k chráněnému prostředku kanálu (případně provádět více vyhodnocení v různých bodech v čase). Jakmile dosáhne konečného rozhodnutí, vaše funkce Azure Functions provede volání HTTP REST do Azure DevOps ke komunikaci rozhodnutí. V každém okamžiku by mělo existovat jediné otevřené připojení HTTP mezi Azure DevOps a vaší implementací kontroly. Tím ušetříte prostředky na straně funkce Azure i na straně Azure Pipelines.

Pokud kontrola projde, může kanál pokračovat v přístupu k chráněnému prostředku a nasazení fáze. Pokud se kontrola nezdaří, fáze se nezdaří. Pokud je v jedné fázi více kontrol, je potřeba před povolením přístupu k chráněným prostředkům předat několik kontrol, ale jedna chyba stačí k selhání fáze.

Doporučená implementace asynchronního režimu pro jednu kontrolu funkce Azure Je znázorněna v následujícím diagramu.

Postup v diagramu:

1. Zkontrolujte doručení. Azure Pipelines se připraví k nasazení fáze kanálu a vyžaduje přístup k chráněnému prostředku. Vyvolá odpovídající kontrolu funkce Azure Functions a očekává potvrzení potvrzení voláním končícím stavovým kódem HTTP 200. Nasazení fáze se pozastaví a čeká na rozhodnutí.
2. Zkontrolujte vyhodnocení. K tomuto kroku dochází v implementaci funkce Azure Functions, která běží na vlastních prostředcích Azure a kódu, který je plně pod vaší kontrolou. Vaši funkci Azure Functions doporučujeme postupovat takto:
   • 2.1 Spuštění asynchronní úlohy a vrácení stavového kódu HTTP 200
   • 2.2 Zadejte vnitřní smyčku, ve které může provádět vyhodnocení více podmínek.
   • 2.3 Vyhodnocení podmínek přístupu
   • 2.4 Pokud nemůže dosáhnout konečného rozhodnutí, přeplánujte znovuhodnocení podmínek pro pozdější bod a přejděte ke kroku 2.3.
3. Rozhodovací komunikace. Funkce Azure volá zpět do Azure Pipelines s rozhodnutím o přístupu. Nasazení fáze může pokračovat

Doporučená konfigurace pro asynchronní kontroly

Na panelu konfigurace funkce Azure Nebo rozhraní REST API zkontrolujte, že:

• Vybrané zpětné volání události Dokončení
• Nastavit čas mezi vyhodnoceními (minuty) na 0

Nastavení hodnoty Time mezi vyhodnoceními na nenulovou hodnotu znamená, že rozhodnutí kontroly (pass/ fail) není konečné. Kontrola se znovu zhodnocuje, dokud se všechny ostatní Schválení a kontroly nedostanou do konečného stavu.

Předání informací o spuštění kanálu k kontrolám

Při konfiguraci kontroly můžete zadat informace o spuštění kanálu, které chcete odeslat do kontroly. Minimálně byste měli odeslat:

• "PlanUrl": "$(system.CollectionUri)"
• "ProjectId": "$(system.TeamProjectId)"
• "HubName": "$(system.HostType)"
• "PlanId": "$(system.PlanId)"
• "JobId": "$(system.JobId)"
• "TaskInstanceId": "$(system.TaskInstanceId)"
• "AuthToken": "$(system.AccessToken)"

Tyto páry klíč-hodnota se ve výchozím nastavení nastaví v Headers volání REST provedeném službou Azure Pipelines.

K volání do Azure DevOps byste měli použít AuthToken volání, například při zpětném ověření volání s rozhodnutím.

Volání do Azure DevOps

Pokud chcete dosáhnout rozhodnutí, může kontrola potřebovat informace o aktuálním spuštění kanálu, které se do kontroly nedají předat, takže kontrola ji musí načíst. Představte si, že kontrola ověří, že spuštění kanálu spustilo určitou úlohu, například úlohu statické analýzy. Vaše kontrola musí volat do Azure DevOps a získat seznam již spuštěných úloh.

Pokud chcete volat Azure DevOps, doporučujeme místo tokenu PAT (Personal Access Token) použít přístupový token úlohy vystavený ke kontrole. Token je již poskytnut vašim kontrolám ve výchozím nastavení v hlavičce AuthToken .

V porovnání s paty je přístupový token úlohy méně náchylný k omezování, nepotřebuje ruční aktualizaci a není svázaný s osobním účtem. Token je platný po dobu 48 hodin.

Pomocí přístupového tokenu úlohy se odeberou problémy s omezováním rozhraní REST API Azure DevOps. Když používáte pat, používáte stejné PAT pro všechna spuštění kanálu. Pokud spustíte velký počet kanálů, dojde k omezení patu. Jedná se o méně problém s přístupovým tokenem úlohy, protože se pro každou kontrolu vygeneruje nový token.

Token se vydává pro identitu sestavení, která se používá ke spuštění kanálu, například pro službu sestavení FabrikamFiberChat (FabrikamFiber). Jinými slovy, token lze použít pro přístup ke stejným úložištím nebo spuštění kanálu, které může hostitelský kanál. Pokud jste povolili ochranu přístupu k úložištím v kanálech YAML, jeho rozsah je dále omezen pouze na úložiště odkazovaná při spuštění kanálu.

Pokud vaše kontrola potřebuje přístup k prostředkům, které nesouvisejí s kanály, například uživatelské scénáře Boards, měli byste těmto oprávněním udělit identitám sestavení kanálů. Pokud je možné kontrolu aktivovat z více projektů, ujistěte se, že všechny kanály ve všech projektech mají přístup k požadovaným prostředkům.

Odeslání rozhodnutí zpět do Azure DevOps

Vaše implementace kontroly musí ke komunikaci s Azure Pipelines použít volání rozhraní REST API post event . Ujistěte se, že jste zadali následující vlastnosti:

• Headers: Basic: {AuthToken}
• Body:

{
    "name": "TaskCompleted",
    "taskId": "{TaskInstanceId}",
    "jobId": "{JobId}",
    "result": "succeeded|failed"
}

Odesílání aktualizací stavu do Azure DevOps z kontrol

Pomocí rozhraní REST API služby Azure Pipelines můžete uživatelům služby Azure Pipelines poskytnout aktualizace stavu. Tato funkce je užitečná, například pokud chcete dát uživatelům vědět, že kontrola čeká na externí akci, například někdo potřebuje schválit lístek ServiceNow.

Postup odeslání aktualizací stavu:

1. Vytvoření protokolu úloh
2. Připojení k protokolu úloh
3. Aktualizace záznamu časové osy

Všechna volání rozhraní REST API musí být ověřena.

Příklady

Základní kontrola funkce Azure

V tomto základním příkladu funkce Azure Functions zkontroluje, že vyvolání kanálu spustilo CmdLine úlohu před udělením přístupu k chráněnému prostředku.

Funkce Azure Functions prochází následujícími kroky:

1. Potvrdí přijetí datové části kontroly.
2. Odešle aktualizaci stavu do Služby Azure Pipelines, kterou kontrola spustila.
3. Používá {AuthToken} k načtení položky časové osy spuštění kanálu zpětné volání do Služby Azure Pipelines.
4. Zkontroluje, jestli časová osa obsahuje úkol s "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" (ID CmdLine úkolu).
5. Odešle aktualizaci stavu s výsledkem hledání.
6. Odešle rozhodnutí o kontrole do Azure Pipelines.

Tento příklad si můžete stáhnout z GitHubu.

Pokud chcete použít tuto kontrolu funkce Azure Functions, musíte při konfiguraci kontroly zadat následující Headers :

{
    "Content-Type":"application/json", 
    "PlanUrl": "$(system.CollectionUri)", 
    "ProjectId": "$(system.TeamProjectId)", 
    "HubName": "$(system.HostType)", 
    "PlanId": "$(system.PlanId)", 
    "JobId": "$(system.JobId)", 
    "TimelineId": "$(system.TimelineId)", 
    "TaskInstanceId": "$(system.TaskInstanceId)", 
    "AuthToken": "$(system.AccessToken)",
    "BuildId": "$(build.BuildId)"
}

Rozšířená kontrola funkce Azure Functions

V tomto pokročilém příkladu funkce Azure Functions zkontroluje, jestli je pracovní položka Azure Boards odkazovaná ve zprávě potvrzení, která aktivovala spuštění kanálu, ve správném stavu.

Funkce Azure Functions prochází následujícími kroky:

1. Potvrdí přijetí datové části kontroly.
2. Odešle aktualizaci stavu do Služby Azure Pipelines, kterou kontrola spustila.
3. Používá {AuthToken} k zpětnému volání do Azure Pipelines k načtení stavu pracovní položky Azure Boards odkazované ve zprávě potvrzení, která aktivovala spuštění kanálu.
4. Zkontroluje, jestli je pracovní položka ve Completed stavu.
5. Odešle aktualizaci stavu s výsledkem kontroly.
6. Pokud pracovní položka není ve Completed stavu, přeplánuje další vyhodnocení za 1 minutu.
7. Jakmile je pracovní položka ve správném stavu, odešle do Azure Pipelines pozitivní rozhodnutí.

Tento příklad si můžete stáhnout z GitHubu.

Pokud chcete použít tuto kontrolu funkce Azure Functions, musíte při konfiguraci kontroly zadat následující Headers :

{
    "Content-Type":"application/json", 
    "PlanUrl": "$(system.CollectionUri)", 
    "ProjectId": "$(system.TeamProjectId)", 
    "HubName": "$(system.HostType)", 
    "PlanId": "$(system.PlanId)", 
    "JobId": "$(system.JobId)", 
    "TimelineId": "$(system.TimelineId)", 
    "TaskInstanceId": "$(system.TaskInstanceId)", 
    "AuthToken": "$(system.AccessToken)",
    "BuildId": "$(build.BuildId)"
}

Zpracování chyb

Azure Pipelines v současné době vyhodnotí jednu instanci kontroly maximálně 2 000krát.

Pokud vaše kontrola nevolá zpět do Azure Pipelines v rámci nakonfigurovaného časového limitu, přidružená fáze se přeskočí. Fáze v závislosti na tom se také přeskočí.

Synchronní kontroly

V synchronním režimu Azure DevOps volá funkci Azure Functions nebo rozhraní REST API a získá okamžité rozhodnutí, jestli je povolený přístup k chráněnému prostředku nebo ne.

Implementace režimu synchronizace pro jednu kontrolu funkce Azure Je znázorněna v následujícím diagramu.

Postupujte takto:

1. Azure Pipelines se připraví k nasazení fáze kanálu a vyžaduje přístup k chráněnému prostředku.
2. Vstoupí do vnitřní smyčky, ve které:

• 2.1. Azure Pipelines vyvolá odpovídající kontrolu funkce Azure a čeká na rozhodnutí.
• 2.2. Vaše funkce Azure Functions vyhodnotí podmínky potřebné k povolení přístupu a vrátí rozhodnutí.
• 2.3. Pokud tělo odpovědi funkce Azure nevyhovuje kritériím úspěchu, která jste definovali, a doba mezi vyhodnoceními není nulová, Azure Pipelines přeplánuje další vyhodnocení kontroly po vyhodnocení mezi vyhodnoceními.

Konfigurace synchronních kontrol

Pokud chcete použít synchronní režim pro rozhraní Azure Functions / REST API, ujistěte se, že na panelu konfigurace kontroly:

• Selected ApiResponse for the Completion event under Advanced
• Zadali jsme kritéria úspěchu, která definují, kdy předat kontrolu na základě textu odpovědi kontroly.
• Nastavení času mezi vyhodnoceními na hodnotu 0 v části Možnosti ovládacího prvku
• Nastavte časový limit na dobu, po kterou chcete počkat na úspěšné ověření. Pokud nedojde k pozitivnímu rozhodnutí a dosáhnete časového limitu , přeskočí se odpovídající fáze kanálu.

Nastavení Doba mezi vyhodnoceními určuje, jak dlouho je rozhodnutí kontroly platné. Hodnota 0 znamená, že rozhodnutí je konečné. Nenulová hodnota znamená, že se kontrola bude opakovat po nakonfigurovaném intervalu, když je její rozhodnutí záporné. Pokud je spuštěno více Schválení a kontrol, kontrola se opakuje bez ohledu na rozhodnutí.

Maximální počet vyhodnocení je definován poměrem mezi časovým limitem a časem mezi hodnotami vyhodnocení . Doporučujeme zajistit, aby tento poměr byl maximálně 10.

Předání informací o spuštění kanálu k kontrolám

Při konfiguraci kontroly můžete zadat informace o spuštění kanálu, které chcete odeslat do funkce Azure Nebo do kontroly rozhraní REST API. Azure Pipeline ve výchozím nastavení přidá do volání HTTP následující informace Headers .

• "PlanUrl": "$(system.CollectionUri)"
• "ProjectId": "$(system.TeamProjectId)"
• "HubName": "$(system.HostType)"
• "PlanId": "$(system.PlanId)"
• "JobId": "$(system.JobId)"
• "TaskInstanceId": "$(system.TaskInstanceId)"
• "AuthToken": "$(system.AccessToken)"

V synchronním režimu nedoporučujeme provádět volání do Azure DevOps, protože vaše kontrola pravděpodobně bude trvat déle než 3 sekundy, takže se kontrola nezdaří.

Zpracování chyb

Azure Pipelines v současné době vyhodnotí jednu instanci kontroly maximálně 2 000krát.

Kdy použít asynchronní a synchronní kontroly

Podívejme se na některé příklady případů použití a na doporučený typ kontrol, které se mají použít.

Externí informace musí být správné.

Řekněme, že máte službu Připojení ion k produkčnímu prostředku a chcete zajistit, aby byl přístup k němu povolený jenom v případě, že jsou informace v lístku ServiceNow správné. V tomto případě by tok byl následující:

• Přidáte asynchronní kontrolu funkce Azure Functions, která ověří správnost lístku ServiceNow.
• Když se spustí kanál, který chce používat službu Připojení ion:
  • Azure Pipelines volá funkci kontroly.
  • Pokud jsou informace nesprávné, vrátí kontrola negativní rozhodnutí. Předpokládejme tento výsledek.
  • Fáze kanálu selže.
  • Aktualizujete informace v lístku ServiceNow.
  • Restartujete neúspěšnou fázi.
  • Kontrola se spustí znovu a tentokrát proběhne úspěšně.
  • Spuštění kanálu pokračuje.

Externí schválení musí být uděleno.

Řekněme, že máte službu Připojení ion k produkčnímu prostředku a chcete zajistit, aby byl přístup k němu povolený až po schválení lístku ServiceNow správcem. V tomto případě by tok byl následující:

• Přidáte asynchronní kontrolu funkce Azure Functions, která ověří schválení lístku ServiceNow.
• Když se spustí kanál, který chce používat službu Připojení ion:
  • Azure Pipelines volá funkci kontroly.
  • Pokud lístek ServiceNow není schválený, funkce Azure odešle aktualizaci do Služby Azure Pipelines a znovu ji přeplánuje, aby zkontrolovala stav lístku za 15 minut.
  • Po schválení lístku kontrola volání zpět do Služby Azure Pipelines s pozitivním rozhodnutím
  • Spuštění kanálu pokračuje.

Postup vývoje byl dodržen.

Řekněme, že máte službu Připojení ion k produkčnímu prostředku a chcete zajistit, aby byl přístup k němu povolený pouze v případě, že pokrytí kódu překračuje 80 %. V tomto případě by tok byl následující:

• Kanál napíšete takovým způsobem, že selhání fáze způsobí selhání sestavení.
• Přidáte asynchronní kontrolu funkce Azure Functions, která ověří pokrytí kódu pro přidružené spuštění kanálu.
• Když se spustí kanál, který chce používat službu Připojení ion:
  • Azure Pipelines volá funkci kontroly.
  • Pokud není splněna podmínka pokrytí kódu, vrátí kontrola negativní rozhodnutí. Předpokládejme tento výsledek.
  • Selhání kontroly způsobí selhání fáze, což způsobí selhání spuštění kanálu.
• Technický tým přidá potřebné testy jednotek pro dosažení 80% pokrytí kódu.
• Aktivuje se nové spuštění kanálu a tentokrát se kontrola projde.
  • Spuštění kanálu pokračuje.

Musí být splněna kritéria výkonu.

Řekněme, že nasazujete nové verze systému v několika krocích, počínaje kanárovým nasazením. Chcete zajistit, aby výkon vašeho kanárského nasazení byl odpovídající. V tomto případě by tok byl následující:

• Přidáte asynchronní kontrolu funkce Azure Functions.
• Když se spustí kanál, který chce používat službu Připojení ion:
  • Azure Pipelines volá funkci kontroly.
  • Kontrola spustí monitorování výkonu kanárského nasazení.
  • Kontrola plánuje několik kontrolních bodů vyhodnocení, abyste zjistili, jak se výkon vyvinul.
  • Jakmile získáte dostatečnou jistotu o výkonu kanárského nasazení, funkce Azure Functions zavolá zpět do Služby Azure Pipelines s pozitivním rozhodnutím.
  • Spuštění kanálu pokračuje.

Důvod nasazení musí být platný.

Řekněme, že máte službu Připojení ion k prostředku produkčního prostředí a chcete zajistit, aby k němu došlo pouze u ručně zařazených sestavení do fronty. V tomto případě by tok byl následující:

• Přidáte synchronní kontrolu funkce Azure Functions, která ověří, že Build.Reason pro spuštění kanálu je Manual
• Nakonfigurujete kontrolu funkce Azure Functions tak, aby předávala Build.Reason její Headers
• Čas kontroly mezi vyhodnoceními nastavíte na hodnotu 0, takže selhání nebo průchod je konečný a není nutné provádět žádné vyhodnocení.
• Když se spustí kanál, který chce používat službu Připojení ion:
  • Azure Pipelines volá funkci kontroly.
  • Pokud je důvod jiný než Manual, kontrola selže a spuštění kanálu selže.

Více kontrol

Než Azure Pipelines nasadí fázi spuštění kanálu, může být potřeba provést několik kontrol. Chráněný prostředek může mít přidruženou jednu nebo více kontrol. Fáze může používat více chráněných prostředků. Azure Pipelines shromažďuje všechny kontroly přidružené ke každému chráněnému prostředku používanému ve fázi a vyhodnocuje je souběžně.

Spuštění kanálu je povoleno nasadit do fáze pouze v případech, kdy všechny kontroly proběhnou současně. Jediné konečné záporné rozhodnutí způsobí, že kanál bude odepřen přístup a fáze selže.

Při použití kontrol doporučeným způsobem (asynchronní, s konečnými stavy) se jejich rozhodnutí o přístupu dokončí a usnadní pochopení stavu systému.

Příklady najdete v části Více Schválení a Kontroly.

Další informace

• Schválení a kontroly
• Vyvolání úlohy funkce Azure Functions
• Vyvolání úlohy rozhraní REST API