Azure Function/REST API-controles aanroepen

Met de controles voor het aanroepen van Azure-functie/REST API kunt u code schrijven om te bepalen of een specifieke pijplijnfase toegang heeft tot een beveiligde resource of niet. Deze controles kunnen in twee modi worden uitgevoerd:

• Asynchroon (aanbevolen): pushmodus, waarin Azure DevOps wacht op de implementatie van de Azure-functie/REST API om terug te bellen naar Azure DevOps met een fasetoegangsbeslissing
• Synchroon: poll-modus, waarin Azure DevOps periodiek de Azure-functie/REST API aanroept om een beslissing voor fasetoegang te krijgen

In de rest van deze handleiding verwijzen we naar Azure Function/REST API Checks gewoon als controles.

De aanbevolen manier om controles te gebruiken, bevindt zich in de asynchrone modus. Deze modus biedt u het hoogste controleniveau over de controlelogica, maakt het eenvoudig om te redeneren over de status waarin het systeem zich bevindt en koppelt Azure Pipelines los van uw controles-implementatie, wat de beste schaalbaarheid biedt. Alle synchrone controles kunnen worden geïmplementeerd met behulp van de asynchrone controlesmodus.

Asynchrone controles

In de asynchrone modus voert Azure DevOps een aanroep uit naar de Azure-functie/REST API-controle en wacht op een callback met de beslissing over resourcetoegang. Er is geen open HTTP-verbinding tussen Azure DevOps en uw controle-implementatie tijdens de wachttijd.

In de rest van deze sectie wordt gesproken over Azure Function-controles, maar tenzij anders vermeld, geldt de richtlijnen ook voor het aanroepen van REST API-controles.

Aanbevolen implementatie van asynchrone controles

De aanbevolen asynchrone modus heeft twee communicatiestappen:

1. Lever de nettolading van de controle. Azure Pipelines maakt een HTTP-aanroep naar uw Azure-functie/REST API alleen om de payload voor de controle te leveren en niet om direct een beslissing te krijgen. Uw functie moet alleen de ontvangst van de informatie bevestigen en de HTTP-verbinding met Azure DevOps beëindigen. De implementatie van de controle moet de HTTP-aanvraag binnen 3 seconden verwerken.
2. Bied toegangsbeslissing via een callback. Uw controle moet asynchroon worden uitgevoerd, de voorwaarde evalueren die nodig is voor de pijplijn om toegang te krijgen tot de beveiligde resource (mogelijk meerdere evaluaties op verschillende tijdstippen uitvoeren). Zodra de azure-functie een definitieve beslissing heeft genomen, maakt uw Azure-functie een HTTP REST-aanroep naar Azure DevOps om de beslissing te communiceren. Op elk moment moet er één open HTTP-verbinding zijn tussen Azure DevOps en uw controle-implementatie. Hierdoor worden resources zowel aan de kant van uw Azure-functie als aan de kant van Azure Pipelines bespaard.

Als er een controle wordt uitgevoerd, kan de pijplijn toegang krijgen tot een beveiligde resource en de fase-implementatie kan doorgaan. Als een controle mislukt, mislukt de fase. Als er meerdere controles in één fase zijn, moeten alle controles worden doorgegeven voordat toegang tot beveiligde resources is toegestaan, maar één fout is voldoende om de fase te mislukken.

De aanbevolen implementatie van de asynchrone modus voor één Azure Function-controle wordt weergegeven in het volgende diagram.

De stappen in het diagram zijn:

1. Controleer de levering. Azure Pipelines bereidt zich voor op het implementeren van een pijplijnfase en vereist toegang tot een beveiligde resource. Hiermee wordt de bijbehorende Azure Function-controle aangeroepen en verwacht men bevestiging van ontvangst, nadat de oproep eindigt met een HTTP 200-statuscode. Fase-implementatie is onderbroken in afwachting van een beslissing.
2. Controleer de evaluatie. Deze stap vindt plaats in uw Azure Function-implementatie, die wordt uitgevoerd op uw eigen Azure-resources en waarvan de code volledig onder uw controle staat. Uw Azure-functie wordt aangeraden deze stappen uit te voeren:
   • 2.1 Een asynchrone taak starten en HTTP-statuscode retourneren200
   • 2.2 Voer een binnenste lus in, waarin meerdere voorwaardeevaluaties kunnen worden uitgevoerd
   • 2.3 Evalueer de toegangsvoorwaarden
   • 2.4 Als het geen definitieve beslissing kan bereiken, moet u een herwaardering van de voorwaarden voor een later tijdstip opnieuw plannen en vervolgens naar stap 2.3 gaan
3. Beslissingscommunicatie. De Azure-functie zendt een terugkoppeling naar Azure Pipelines met de beslissing over toegang. Fase-implementatie kan doorgaan

Wanneer u de aanbevolen implementatie gebruikt, wordt op de pagina details van de pijplijnuitvoering het meest recente controlelogboek weergegeven.

Aanbevolen configuratie voor asynchrone controles

Controleer in het configuratievenster van de Azure-functie/REST API of u het volgende doet:

• Geselecteerde callback voor het voltooïngsevenement
• Tijd tussen evaluaties (minuten) instellen op 0

Als u de tijd tussen evaluaties instelt op een niet-nulwaarde, betekent dit dat de controlebeslissing (pass/fail) niet definitief is. De controle wordt opnieuw geëvalueerd totdat alle andere goedkeuringen en controles de definitieve status bereiken.

Informatie over pijplijnuitvoering doorgeven aan controles

Wanneer u de controle configureert, kunt u de gegevens voor de pijplijnuitvoering opgeven die u naar uw controle wilt verzenden. U moet minimaal het volgende verzenden:

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

Deze sleutel-waardeparen worden standaard ingesteld in de Headers REST-aanroep van Azure Pipelines.

U moet AuthToken gebruiken om aanroepen naar Azure DevOps te doen, bijvoorbeeld wanneer uw controle terugkomt met een beslissing.

Aanroepen in Azure DevOps

Om tot een beslissing te komen, heeft uw controleproces mogelijk informatie nodig over de huidige pijplijnuitvoering die niet kan worden meegestuurd naar het controleproces, dus moet het controleproces deze zelf ophalen. Stel dat uw controle controleert of een pijplijnuitvoering een bepaalde taak heeft uitgevoerd, bijvoorbeeld een statische analysetaak. Uw controle moet azure DevOps aanroepen en de lijst met al uitgevoerde taken ophalen.

Als u Azure DevOps wilt inbellen, raden we u aan het taaktoegangstoken te gebruiken dat is uitgegeven voor de uitvoering van de controle, in plaats van een persoonlijk toegangstoken (PAT). Het token is standaard al aan uw controles toegevoegd, in de AuthToken koptekst.

Vergeleken met PAW's is het toegangstoken voor werk minder gevoelig voor afklemming, hoeft het niet handmatig te worden vernieuwd en is het niet gekoppeld aan een persoonlijk account. Het token is 48 uur geldig.

Door het toegangstoken voor de taak te gebruiken, worden problemen met snelheidsbeperkingen van de Azure DevOps REST API vrijwel geëlimineerd. Wanneer u een PAT gebruikt, gebruikt u dezelfde PAT voor alle uitvoeringen van uw pijplijn. Als u een groot aantal pijplijnen uitvoert, wordt de PAT beperkt. Dit is minder problematisch met het toegangstoken voor de taak, omdat voor elke uitvoering van een controle een nieuw token wordt gegenereerd.

Het token wordt uitgegeven voor de build-identiteit die wordt gebruikt om een pijplijn uit te voeren, bijvoorbeeld voor de FabrikamFiberChat-buildservice (FabrikamFiber). Met andere woorden, het token kan worden gebruikt voor toegang tot dezelfde repositories of pijplijnuitvoeringen die de hostpijplijn kan uitvoeren. Als u Toegang tot opslagplaatsen in YAML-pijplijnen beveiligen hebt ingeschakeld, wordt het bereik verder beperkt tot alleen de opslagplaatsen waarnaar wordt verwezen in de pijplijnuitvoering.

Als uw controle toegang moet hebben tot middelen die niet gerelateerd zijn aan pijplijnen, zoals gebruikersverhalen op borden, moet u dergelijke machtigingen verlenen aan de bouwidentiteiten van de pijplijnen. Als uw controle kan worden geactiveerd vanuit meerdere projecten, moet u ervoor zorgen dat alle pijplijnen in alle projecten toegang hebben tot de vereiste resources.

Een beslissing terugsturen naar Azure DevOps

Uw controle-implementatie moet de REST API-aanroep na de gebeurtenis gebruiken om een beslissing terug te geven naar Azure Pipelines. Zorg ervoor dat u de volgende eigenschappen opgeeft:

• Headers: Bearer {AuthToken}
• Body:

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

Statusupdates verzenden naar Azure DevOps vanuit controles

U kunt statusupdates opgeven voor Azure Pipelines-gebruikers vanuit uw controles met behulp van REST API's van Azure Pipelines. Deze functionaliteit is bijvoorbeeld handig als u gebruikers wilt laten weten dat de controle wacht op een externe actie, zoals iemand moet een ServiceNow-ticket goedkeuren.

De stappen voor het verzenden van statusupdates zijn:

1. Een taaklogboek maken
2. Toevoegen aan het taaklogboek
3. Tijdlijnrecord bijwerken

Alle REST API-aanroepen moeten worden geverifieerd.

Voorbeelden

Basiscontrole van Azure-functie

In dit basisvoorbeeld controleert de Azure-functie of de aanroepende pijplijn een CmdLine taak heeft uitgevoerd voordat deze toegang verleent tot een beveiligde resource.

De Azure-functie doorloopt de volgende stappen:

1. Bevestigt de ontvangst van de controlelading
2. Hiermee wordt een statusupdate verzonden naar Azure Pipelines waarmee de controle is gestart
3. Hiermee maakt u via {AuthToken} een callback naar Azure Pipelines om de tijdlijnvermelding van de pijplijnuitvoering op te halen.
4. Controleert of de tijdlijn een taak bevat met "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" (de id van de CmdLine taak)
5. Hiermee wordt een statusupdate verzonden met het resultaat van de zoekopdracht
6. Een controlebeslissing naar Azure Pipelines verzenden

U kunt dit voorbeeld downloaden van GitHub.

Als u deze Azure Function-controle wilt gebruiken, moet u het volgende Headers opgeven bij het configureren van de controle:

{
    "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)"
}

Geavanceerde azure-functiecontrole

In dit geavanceerde voorbeeld controleert de Azure-functie of het Azure Boards-werkitem waarnaar wordt verwezen in het doorvoerbericht waarnaar de pijplijnuitvoering is geactiveerd, de juiste status heeft.

De Azure-functie doorloopt de volgende stappen:

1. Bevestigt de ontvangst van de controle-payload
2. Hiermee wordt een statusupdate verzonden naar Azure Pipelines waarmee de controle is gestart
3. Hiermee {AuthToken} maakt u een callback naar Azure Pipelines om de status van het Azure Boards-werkitem op te halen waarnaar wordt verwezen in het doorvoerbericht dat de pijplijnuitvoering heeft geactiveerd
4. Controleert of het werkitem de Completed status heeft
5. Hiermee wordt een statusupdate verzonden met het resultaat van de controle
6. Als het werkitem niet de Completed status heeft, wordt een andere evaluatie over 1 minuut opnieuw gepland
7. Zodra het werkitem de juiste status heeft, wordt er een positieve beslissing naar Azure Pipelines verzonden

U kunt dit voorbeeld downloaden van GitHub.

Als u deze Azure Function-controle wilt gebruiken, moet u het volgende Headers opgeven bij het configureren van de controle:

{
    "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)"
}

Foutafhandeling

Op dit moment evalueert Azure Pipelines maximaal 2.000 keer een enkele controle-instantie.

Als uw controleproces niet binnen de ingestelde tijdslimiet terugbelt naar Azure Pipelines, wordt de bijbehorende fase overgeslagen. Fasen die ervan afhankelijk zijn, worden ook overgeslagen.

Synchrone controles

In de synchrone modus voert Azure DevOps een aanroep uit naar de Azure-functie/REST API om direct te bepalen of toegang tot een beveiligde resource is toegestaan of niet.

De implementatie van de synchronisatiemodus voor één Azure Function-controle wordt weergegeven in het volgende diagram.

Dit zijn de stappen:

1. Azure Pipelines bereidt zich voor op het implementeren van een pijplijnfase en vereist toegang tot een beveiligde resource
2. Het voert een binnenste lus in waarin:

• 2.1. Azure Pipelines roept de bijbehorende Azure-functiecontrole aan en wacht op een beslissing
• 2.2. Uw Azure-functie evalueert de voorwaarden die nodig zijn om toegang te verlenen en retourneert een beslissing
• 2.3. Als de antwoordtekst van de Azure-functie niet voldoet aan de succescriteria die u hebt gedefinieerd en de tijd tussen evaluaties niet nul is, worden in Azure Pipelines een andere controle-evaluatie gepland na tijd tussen evaluaties

Synchrone controles configureren

Als u de synchrone modus voor de Azure-functie/REST API wilt gebruiken, controleert u het volgende in het configuratiepaneel:

• Geselecteerde ApiResponse voor de voltooingsgebeurtenis onder Geavanceerd
• Gespecificeerd de succescriteria die bepalen wanneer de controle wordt geslaagd, gebaseerd op de antwoordinhoud van de controle.
• Tijd tussen evaluaties instellen op 0 onder Opties voor Beheer
• Stel Time-out in op hoe lang u wilt wachten tot een controle is geslaagd. Als er geen positieve beslissing en time-out is bereikt, wordt de bijbehorende pijplijnfase overgeslagen

De instelling Tijd tussen evaluaties bepaalt hoe lang de beslissing van de controle geldig is. Een waarde van 0 betekent dat de beslissing definitief is. Een niet-nulwaarde betekent dat de controle opnieuw wordt uitgevoerd na het geconfigureerde interval, wanneer de beslissing negatief is. Wanneer meerdere goedkeuringen en controles worden uitgevoerd, wordt de controle opnieuw geprobeerd, ongeacht de beslissing.

Het maximum aantal evaluaties wordt gedefinieerd door de verhouding tussen de time-out en de tijd tussen de evaluatiewaarden . We raden u aan ervoor te zorgen dat deze verhouding maximaal 10 is.

Informatie over pijplijnuitvoering doorgeven aan controles

Wanneer u de controle configureert, kunt u de gegevens voor de pijplijnuitvoering opgeven die u naar uw Azure-functie/REST API-controle wilt verzenden. Standaard voegt Azure Pipeline de volgende informatie toe in de Headers HTTP-aanroep die wordt gemaakt.

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

Het is niet raadzaam om Azure DevOps in de synchrone modus aan te roepen, omdat de controle waarschijnlijk meer dan 3 seconden duurt om te reageren, waardoor de controle mislukt.

Foutafhandeling

Azure Pipelines evalueert op dit moment een enkel controle-exemplaar maximaal 2000 keer.

Wanneer asynchrone versus synchrone controles worden gebruikt

Laten we eens kijken naar enkele voorbeeldgebruiksvoorbeelden en wat het aanbevolen type controles is dat moet worden gebruikt.

Externe informatie moet juist zijn

Stel dat u een serviceverbinding hebt met een productieresource en u wilt ervoor zorgen dat toegang tot deze resource alleen is toegestaan als de informatie in een ServiceNow-ticket juist is. In dit geval is de stroom als volgt:

• U voegt een asynchrone Azure-functiecontrole toe die de juistheid van het ServiceNow-ticket verifieert
• Wanneer een pipeline die de Service Connection wil gebruiken, wordt uitgevoerd:
  • Azure Pipelines roept uw controlefunctie aan
  • Als de informatie onjuist is, retourneert de controle een negatieve beslissing. Stel je dit resultaat voor
  • De pijplijnfase mislukt
  • U werkt de informatie in het ServiceNow-ticket bij
  • U start de mislukte fase opnieuw op
  • De controle wordt opnieuw uitgevoerd en slaagt deze keer.
  • De pijplijnuitvoering wordt voortgezet

Externe goedkeuring moet worden verleend

Stel dat u een serviceverbinding hebt met een productieresource en u wilt ervoor zorgen dat toegang tot deze resource alleen is toegestaan nadat een beheerder een ServiceNow-ticket heeft goedgekeurd. In dit geval is de stroom als volgt:

• U voegt een asynchrone Azure-functiecontrole toe die controleert of het ServiceNow-ticket is goedgekeurd
• Wanneer een pijplijn draait die de serviceverbinding wil gebruiken:
  • Azure Pipelines roept uw validatiefunctie aan.
  • Als het ServiceNow-ticket niet is goedgekeurd, stuurt de Azure-functie een update naar Azure Pipelines en plant zichzelf opnieuw in om de status van het ticket over 15 minuten te controleren.
  • Zodra het ticket is goedgekeurd, worden de aanroepen teruggezet naar Azure Pipelines met een positieve beslissing
  • De pijplijnuitvoering wordt voortgezet

Het ontwikkelingsproces is gevolgd

Stel dat u een serviceverbinding hebt met een productieresource en u wilt ervoor zorgen dat toegang tot deze resource alleen is toegestaan als de codedekking hoger is dan 80%. In dit geval is de stroom als volgt:

• U schrijft uw pijplijn zodanig dat fasefouten ertoe leiden dat de build mislukt
• U voegt een asynchrone Azure-functie toe om de codedekking voor de bijbehorende pijplijnuitvoering te controleren
• Wanneer een pijplijn die de serviceverbinding wil gebruiken wordt uitgevoerd:
  • Azure Pipelines roept uw controlefunctie aan
  • Als niet aan de voorwaarde voor de codedekking wordt voldaan, retourneert de controle een negatieve beslissing. Stel dit resultaat voor
  • De controlefout zorgt ervoor dat uw fase mislukt, waardoor de pijplijnuitvoering mislukt
• Het technische team voegt de benodigde eenheidstests toe om de codedekking van 80% te bereiken
• Er wordt een nieuwe pijplijnuitvoering geactiveerd en deze keer is de validatie geslaagd.
  • De pijplijnuitvoering wordt voortgezet

Aan prestatiecriteria moet worden voldaan

Stel dat u in meerdere stappen nieuwe versies van uw systeem implementeert, te beginnen met een canary-implementatie. U wilt ervoor zorgen dat de prestaties van uw canary-implementatie voldoende zijn. In dit geval is de stroom als volgt:

• U voegt een asynchrone Azure-functiecontrole toe
• Wanneer een pijplijn die de serviceverbinding wil gebruiken wordt uitgevoerd:
  • Azure Pipelines roept uw controlefunctie aan
  • De controle start een monitor van de prestaties van de canary-implementatie
  • Het controlemechanisme plant meerdere evaluatiemomenten om te zien hoe de prestaties zich hebben ontwikkeld.
  • Zodra u voldoende vertrouwen hebt in de prestaties van een canary-implementatie, stuurt uw Azure-functie een terugkoppeling naar Azure Pipelines met een positieve beslissing.
  • De pijplijnuitvoering wordt voortgezet

De reden van de implementatie moet geldig zijn

Stel dat u een serviceverbinding hebt met een productieomgevingsresource en u wilt ervoor zorgen dat de toegang tot deze alleen plaatsvindt voor handmatig in de wachtrij geplaatste builds. In dit geval is de stroom als volgt:

• U voegt een synchrone Azure-functiecontrole toe die verifieert dat Build.Reason voor de pijplijnuitvoering Manual is.
• Configureer de controle voor de Azure-functie om Build.Reason door te geven in Headers
• U stelt de tijd van de controle tussen evaluaties in op 0, dus fout of pass is definitief en er is geen herwaardering nodig
• Wanneer een pijplijn die de serviceverbinding wil gebruiken, wordt uitgevoerd:
  • Azure Pipelines roept uw controlefunctie aan
  • Als de reden anders is dan Manual, mislukt de controle en mislukt de pijplijnuitvoering

Controleren op naleving

Azure Function- en REST API-controles omvatten nu regels die overeenkomen met het aanbevolen gebruik. Controles moeten deze regels volgen, afhankelijk van de modus en het aantal nieuwe pogingen:

• Asynchrone controles (callbackmodus):Azure Pipelines voert asynchrone controles niet opnieuw uit. U moet asynchroon een resultaat opgeven wanneer een evaluatie is voltooid. Voor asynchrone controles die als compatibel moeten worden beschouwd, moet het tijdsinterval tussen evaluaties 0 zijn.

• Synchrone controles (ApiResponse-modus): het maximum aantal nieuwe pogingen voor uw controle is 10. U kunt op verschillende manieren instellen. U kunt bijvoorbeeld een time-out instellen op 20 en een tijdsinterval tussen evaluaties tot 2. U kunt ook een time-out instellen op 100 en tijdsinterval tussen evaluaties tot 10. Maar als u time-out configureert op 100 en het tijdsinterval tussen evaluaties instelt op 2, voldoet uw controle niet omdat u om 50 nieuwe pogingen vraagt. De verhouding tussen time-out en tijdsinterval tussen evaluaties moet kleiner zijn dan of gelijk zijn aan 10.

Meer informatie over de implementatie van controlecompatibiliteit.

Meerdere controles

Voordat Azure Pipelines een fase in een pijplijnuitvoering implementeert, moeten mogelijk eerst meerdere controles worden goedgekeurd. Aan een beveiligde resource zijn mogelijk een of meer controles gekoppeld. In een fase kunnen meerdere beveiligde middelen worden gebruikt. Azure Pipelines verzamelt alle controles die zijn gekoppeld aan elke beveiligde resource die in een fase wordt gebruikt en evalueert deze gelijktijdig.

Een pijplijnuitvoering mag alleen worden geïmplementeerd in een fase wanneer alle controles tegelijkertijd geslaagd zijn. Eén laatste negatieve beslissing zorgt ervoor dat de pijplijn de toegang wordt geweigerd en dat de fase mislukt.

Wanneer u controles op de aanbevolen manier (asynchroon, met definitieve statussen) gebruikt, worden hun toegangsbeslissingen definitief gemaakt en wordt inzicht in de status van het systeem.

Bekijk de sectie Meerdere goedkeuringen en controles voor voorbeelden.

Meer informatie

• Goedkeuringen en keuringen
• Azure-functietaak aanroepen
• REST API-taak aanroepen