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 om alleen de nettolading van de controle te leveren en geen beslissing ter plaatse te ontvangen. 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 zijde van uw Azure-functie als aan de kant van Azure Pipelines opgeslagen.

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 Controle van De Azure-functie aangeroepen en wordt bevestiging van ontvangst verwacht, door de aanroep te eindigen 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 roept terug naar Azure Pipelines met de toegangsbeslissing. 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 de voltooiingsbeurtenis
• 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 dit gebruiken AuthToken om aanroepen naar Azure DevOps te maken, bijvoorbeeld wanneer u terugbelt met een beslissing.

Aanroepen naar Azure DevOps

Als u een beslissing wilt nemen, heeft uw controle mogelijk informatie nodig over de huidige pijplijnuitvoering die niet kan worden doorgegeven aan de controle, dus de controle moet deze 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 taken minder gevoelig voor het beperken, hoeft het niet handmatig te vernieuwen en is het niet gekoppeld aan een persoonlijk account. Het token is 48 uur geldig.

Als u het toegangstoken voor de taak gebruikt, worden problemen met beperking van de Azure DevOps REST API verwijderd. 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 een probleem met het toegangstoken voor de taak, omdat er voor elke controleuitvoering een nieuw token wordt gegenereerd.

Het token wordt uitgegeven voor de build-identiteit die wordt gebruikt om een pijplijn uit te voeren, bijvoorbeeld fabrikamFiberChat-buildservice (FabrikamFiber). Met andere woorden, het token kan worden gebruikt voor toegang tot dezelfde opslagplaatsen of pijplijnuitvoeringen die de hostpijplijn kan. 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 nodig heeft tot resources die niet aan pijplijnen zijn gerelateerd, bijvoorbeeld gebruikersverhalen in borden, moet u dergelijke machtigingen verlenen voor de build-identiteiten van 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 De 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 nettolading van de controle
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 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 nettolading van de controle
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 2000 keer één controleexemplaren.

Als uw controle niet terugbelt naar Azure Pipelines binnen de geconfigureerde time-out, wordt de bijbehorende fase overgeslagen. Fasen, afhankelijk van het, 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 voltooiingsbeurtenis onder Geavanceerd
• Opgegeven de succescriteria die bepalen wanneer de controle moet worden doorgegeven op basis van de antwoordtekst 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 in de synchrone modus aanroepen naar Azure DevOps te plaatsen, omdat uw controle waarschijnlijk langer dan 3 seconden in beslag neemt om te reageren, zodat de controle mislukt.

Foutafhandeling

Op dit moment evalueert Azure Pipelines maximaal 2000 keer één controleexemplaren.

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 pijplijn die de serviceverbinding wil gebruiken, wordt uitgevoerd:
  • Azure Pipelines roept uw controlefunctie aan
  • Als de informatie onjuist is, retourneert de controle een negatieve beslissing. Stel dat dit resultaat
  • 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 deze keer 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 die de serviceverbinding wil gebruiken, wordt uitgevoerd:
  • Azure Pipelines roept uw controlefunctie aan.
  • Als het ServiceNow-ticket niet is goedgekeurd, verzendt de Azure-functie een update naar Azure Pipelines en wordt de status van het ticket binnen 15 minuten opnieuw gepland om de status van het ticket te controleren
  • Zodra het ticket is goedgekeurd, worden de aanroepen teruggezet naar Azure Pipelines met een positieve beslissing
  • De pijplijnuitvoering wordt voortgezet

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 dat dit resultaat
  • 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 wordt de controle doorgegeven
  • 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
  • De controle plant meerdere evaluatiecontrolepunten om te zien hoe de prestaties zijn ontwikkeld
  • Zodra u voldoende vertrouwen hebt in de prestaties van de canary-implementatie, roept uw Azure-functie met een positieve beslissing terug naar Azure Pipelines
  • 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 controleert of Build.Reason de pijplijnuitvoering is Manual
• U configureert de Azure-functiecontrole om de bijbehorende door te geven Build.ReasonHeaders
• 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 aanroepen bevatten 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 meerdere controles mogelijk worden doorgegeven. Aan een beveiligde resource zijn mogelijk een of meer controles gekoppeld. In een fase kunnen meerdere beveiligde resources 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 in een fase worden geïmplementeerd wanneer alle controles tegelijkertijd worden doorgegeven. 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 controles
• Azure-functietaak aanroepen
• REST API-taak aanroepen