Vyvolat kontroly funkcí Azure / REST API

Kontroly volání Azure funkce / REST API umožňují napsat kód, který rozhoduje, zda má konkrétní etapa kanálu povolený přístup k chráněnému prostředku, či nikoli. Tyto kontroly se můžou spouštět ve dvou režimech:

• Asynchronní (doporučeno): Režim push, ve kterém Azure DevOps čeká na implementaci Azure Function nebo rozhraní REST API, které zavolá zpět do Azure DevOps k rozhodnutí o přístupu ve fázi.
• 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 zbytku tohoto průvodce budeme dále označovat kontroly funkcí Azure/REST API 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á vaši Azure Function / REST API pouze přes HTTP, aby doručil kontrolní část, a ne k okamžitému přijetí rozhodnutí. 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í Vaše kontrola by měla běžet asynchronně, vyhodnotit podmínku potřebnou pro procesní tok, aby měl přístup k chráněnému prostředku (případně prováděním více vyhodnocení v různých okamžicích). 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, všechny musí projít před povolením přístupu k chráněným prostředkům, ale stačí jedna chyba 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řipravuje k nasazení fáze potrubí a vyžaduje přístup k chráněnému prostředku. Vyvolá odpovídající kontrolu funkce Azure a očekává potvrzení, přičemž volání končí stavovým kódem HTTP 200. Nasazení etapy se pozastavilo a čeká na rozhodnutí.
2. Prohlédněte si 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. Doporučujeme, aby vaše funkce Azure postupovala podle těchto kroků:
   • 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 předává rozhodnutí o přístupu zpět do Azure Pipelines. Nasazení fáze může pokračovat

Při použití doporučené implementace se na stránce podrobností spuštění potrubí zobrazí nejnovější kontrolní protokol.

Doporučená konfigurace pro asynchronní kontroly

Na konfiguračním panelu funkce Azure / rozhraní REST API se ujistěte, ž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 běhu 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 jsou ve výchozím nastavení nastaveny v Headers volání REST prováděném službou Azure Pipelines.

K volání do Azure DevOps, například když vaše kontrola vrátí rozhodnutí, byste měli použít AuthToken.

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 použít úlohový přístupový token vystavený ke kontrole místo osobního přístupového tokenu (PAT). 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 menší problém s tokenem přístupu k úloze, protože pro každou kontrolu je vygenerován nový token.

Token se vydává pro identitu sestavení, která se používá ke spuštění pipeline, 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ím kanálů, ke kterým má přístup i 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, jako například uživatelské scénáře Boards, měli byste těmto identitám sestavení služby Pipelines přiřadit potřebná oprávnění. 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.

Odeslat rozhodnutí zpět do Azure DevOps

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

• Headers: Bearer {AuthToken}
• Body:

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

Odesílejte aktualizace stavu z kontrol do Azure DevOps

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 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í obsahu šeku.
2. Odešle aktualizaci stavu do Azure Pipelines, že kontrola byla zahájena.
3. Používá {AuthToken} ke zpětnému volání do služby Azure Pipelines za účelem načtení položky časové osy spuštění kanálu.
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í obsahu šeku.
2. Odešle aktualizaci stavu do Azure Pipelines, že kontrola byla zahájena.
3. Používá {AuthToken} pro zpětné volání do Azure Pipelines k načtení stavu pracovní položky Azure Boards odkazované ve zprávě o potvrzení, která aktivovala spuštění pipeline.
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 úspěšné potvrzení do Azure Pipeline.

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, které na tom závisí, 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řipravuje k nasazení etapy potrubí 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 definovaným kritériím úspěchu a doba mezi vyhodnoceními není nulová, Azure Pipelines přeplánuje další vyhodnocení kontroly po době 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:

• Vybráno ApiResponse pro událost dokončení v pokročilém
• 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 není přijato pozitivní rozhodnutí a je dosaženo časového limitu, odpovídající fáze kanálu se přeskočí.

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 připojení služby 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í potrubí, které chce použít připojení ke službě:
  • Azure Pipelines volá funkci kontroly.
  • Pokud jsou informace nesprávné, vrátí kontrola negativní rozhodnutí. Předpokládejme tento výsledek.
  • Fáze zpracování 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ě.
  • Pokračuje proces v potrubí.

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

Řekněme, že máte připojení služby 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í potrubí, které chce použít připojení ke službě:
  • Azure Pipelines volá vaši kontrolní funkci.
  • 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í požadavku se kontrola zpětně zavolá do služby Azure Pipelines s pozitivním rozhodnutím.
  • Pokračuje proces v potrubí.

Postup vývoje byl dodržen.

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

• Kanál zapíšete takovým způsobem, že selhání v jednotlivých fázích způsobí, že sestavení selže.
• Přidáte asynchronní kontrolu Azure funkce, která ověří pokrytí kódu pro přidružený běh kanálu.
• Když se spustí potrubí, které chce použít připojení ke službě:
  • 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í pipeline a tentokrát kontrola úspěšně proběhne.
  • Pokračuje proces v potrubí.

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 dostačující. V tomto případě by tok byl následující:

• Přidáte asynchronní kontrolu funkce Azure Functions.
• Když se spustí potrubí, které chce použít připojení ke službě:
  • Azure Pipelines volá funkci kontroly.
  • Kontrola spustí monitorování výkonu kanárského nasazení.
  • Kontrola naplánuje několik kontrolních bodů vyhodnocení, aby se zjistilo, jak se výkon změnil.
  • 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.
  • Pokračuje proces v potrubí.

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

Řekněme, že máte připojení služby k prostředku produkčního prostředí a chcete zajistit, aby k němu měl přístup pouze ručně zařazený build. 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í potrubí, které chce použít připojení ke službě:
  • Azure Pipelines volá funkci kontroly.
  • Pokud je důvod jiný než Manual, kontrola selže a spuštění kanálu selže.

Kontrola dodržování předpisů

Vyvolání kontrol funkcí Azure a rozhraní REST API teď zahrnuje pravidla, která odpovídají doporučenému využití. Kontroly musí dodržovat tato pravidla v závislosti na režimu a počtu opakování:

• Asynchronní kontroly (režim zpětného volání):: Azure Pipelines neopakuje asynchronní kontroly. Výsledek byste měli poskytnout asynchronně, když je vyhodnocení konečné. Aby se asynchronní kontroly považovaly za vyhovující, musí být časový interval mezi vyhodnoceními 0.

• Synchronní kontroly (režim ApiResponse):: Maximální počet opakování kontroly je 10. Můžete to udělat několika způsoby. Můžete například nakonfigurovat časový limit na 20 a časový interval mezi vyhodnoceními na 2. Nebo můžete nakonfigurovat časový limit na 100 a časový interval mezi vyhodnoceními na 10. Pokud ale nakonfigurujete časový limit na 100 a nastavíte časový interval mezi vyhodnoceními na 2, nebude kontrola vyhovovat, protože žádáte o 50 opakování. Poměr časového limitu k časovému intervalu mezi vyhodnoceními by měl být menší nebo roven 10.

Přečtěte si další informace o zavedení kontroly dodržování předpisů.

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, jako asynchronní s konečnými stavy, stanou se jejich rozhodnutí o přístupu konečnými a usnadní pochopení stavu systému.

Podívejte se na příklady v části Více schválení a kontrol.

Další informace

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