Richiamare le verifiche della funzione di Azure / API REST

I controlli dell'API REST/Funzione di Azure invoke consentono di scrivere codice per decidere se una fase specifica della pipeline è autorizzata ad accedere o meno a una risorsa protetta. Questi controlli possono essere eseguiti in due modalità:

• Asincrona (scelta consigliata): modalità push, in cui Azure DevOps attende che la Funzione di Azure / API REST chiami di nuovo Azure DevOps con una decisione sull'accesso alla fase.
• Sincrona: modalità di polling, in cui Azure DevOps chiama periodicamente la funzione di Azure/l'API REST per ottenere una decisione di accesso a una fase.

Nella parte restante di questa guida si fa riferimento a Funzioni di Azure/Controlli API REST semplicemente come controlli.

Il modo consigliato per usare i controlli è in modalità asincrona. Questa modalità offre il massimo livello di controllo sulla logica di controllo, semplifica il motivo dello stato in cui si trova il sistema e separa Azure Pipelines dall'implementazione dei controlli, offrendo la migliore scalabilità. Tutti i controlli sincroni possono essere implementati usando la modalità di controllo asincrona.

Controlli asincroni

In modalità asincrona, Azure DevOps effettua una chiamata al controllo dell'API REST/funzione di Azure e attende un callback con la decisione di accesso alle risorse. Non esiste una connessione HTTP aperta tra Azure DevOps e l'implementazione del controllo durante il periodo di attesa.

La parte restante di questa sezione illustra i controlli delle funzioni di Azure, ma, a meno che non diversamente specificato, le linee guida si applicano anche ai controlli dell'API REST invoke.

Implementazione consigliata di controlli asincroni

La modalità asincrona consigliata prevede due passaggi di comunicazione:

1. Recapitare il payload di verifica. Azure Pipelines effettua una chiamata HTTP alla funzione di Azure / API REST solo per recapitare il payload di controllo e non per ricevere una decisione immediatamente. La funzione deve solo confermare la ricezione delle informazioni e terminare la connessione HTTP con Azure DevOps. L'implementazione del controllo deve elaborare la richiesta HTTP entro 3 secondi.
2. Fornire una decisione di accesso tramite un callback. Il controllo deve essere eseguito in modo asincrono, valutare la condizione necessaria per consentire alla pipeline di accedere alla risorsa protetta (possibilmente eseguendo più valutazioni in momenti diversi). Dopo aver raggiunto una decisione finale, la funzione di Azure effettua una chiamata REST HTTP ad Azure DevOps per comunicare la decisione. In qualsiasi momento dovrebbe essere presente una singola connessione HTTP aperta tra Azure DevOps e l'implementazione del controllo. In questo modo le risorse vengono salvate sia sul lato funzione di Azure che sul lato di Azure Pipelines.

Se viene superato un controllo, la pipeline può accedere a una risorsa protetta e alla distribuzione temporanea può continuare. Se un controllo ha esito negativo, allora anche la fase ha esito negativo. Se sono presenti più controlli in un'unica fase, è necessario passare tutti prima che sia consentito l'accesso alle risorse protette, ma un singolo errore è sufficiente per interrompere la fase.

L'implementazione consigliata della modalità asincrona per un singolo controllo della funzione di Azure è illustrata nel diagramma seguente.

I passaggi del diagramma sono:

1. Controlla consegna. Azure Pipelines prepara la distribuzione di una fase della pipeline e richiede l'accesso a una risorsa protetta. Richiama il controllo della funzione di Azure corrispondente e prevede la conferma della ricezione dalla chiamata che termina con un codice di stato HTTP 200. La distribuzione in fase è sospesa in attesa di una decisione.
2. Controllare la valutazione. Questo passaggio si verifica all'interno dell'implementazione della funzione di Azure, che viene eseguita sulle proprie risorse di Azure e il codice di cui è completamente sotto il controllo. Si consiglia che la Azure Function segua questi passaggi:
   • 2.1 Avvia un'attività asincrona e restituisci il codice di stato HTTP 200
   • 2.2 Immettere un ciclo interno, in cui può valutare più condizioni
   • 2.3 Valutare le condizioni di accesso
   • 2.4 Se non riesce a raggiungere una decisione finale, riprogrammare una rivalutazione delle condizioni per un punto successivo, andare al passaggio 2.3
3. Comunicazione decisionale. La funzione di Azure chiama nuovamente Azure Pipelines con la decisione di accesso. La distribuzione in fase può continuare

Configurazione consigliata per i controlli asincroni

Nel pannello di configurazione di verifica della funzione di Azure/API REST, assicurati di:

• Selezionato callback per l'evento completion
• Impostare Tempo tra valutazioni (minuti) su 0

L'impostazione del Tempo tra le valutazioni su un valore diverso da zero indica che la decisione di verifica (pass / fail) non è definitiva. Il controllo viene rivalutato fino a quando tutte le altre approvazioni e controlli non raggiungono uno stato finale.

Trasferire le informazioni di esecuzione della pipeline ai controlli

Quando si configura il controllo, è possibile definire le informazioni sull'esecuzione della pipeline da inviare al controllo stesso. È necessario inviare almeno:

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

Queste coppie chiave-valore vengono impostate, per impostazione predefinita, nella Headers chiamata REST effettuata da Azure Pipelines.

È consigliabile usare AuthToken per effettuare chiamate ad Azure DevOps, ad esempio quando il controllo richiama con una decisione.

Effettuare una chiamata verso Azure DevOps

Per prendere una decisione, il controllo potrebbe aver bisogno di informazioni sull'esecuzione corrente della pipeline che non possono essere trasmesse al controllo, quindi il controllo deve recuperarle. Si supponga che il controllo verifichi che un'esecuzione della pipeline esegua un'attività specifica, ad esempio un'attività di analisi statica. La verifica deve chiamare Azure DevOps e ottenere l'elenco delle attività già eseguite.

Per chiamare Azure DevOps, è consigliabile usare il token di accesso al processo rilasciato per l'esecuzione del controllo, anziché un token di accesso personale (PAT). Il token viene già fornito in fase di verifica per impostazione predefinita, nell'intestazione AuthToken.

Rispetto ai Token di Accesso Personale (PATs), il token di accesso al lavoro è meno soggetto a limitazioni, non richiede aggiornamenti manuali e non è associato a un account personale. Il token è valido per 48 ore.

Utilizzando il token di accesso, si riducono quasi completamente i problemi di limitazione dell'API REST di Azure DevOps. Quando si usa un token di accesso personale (PAT), si usa lo stesso PAT per tutte le esecuzioni della pipeline. Se si esegue un numero elevato di pipeline, il PAT viene sottoposto a limitazioni. Questo problema si presenta meno con il token di accesso al processo, poiché viene generato un nuovo token ad ogni esecuzione del controllo.

Il token viene rilasciato per l'identità di compilazione utilizzata per eseguire una pipeline, ad esempio il servizio di compilazione FabrikamFiberChat (FabrikamFiber). In altre parole, il token può essere usato per accedere agli stessi repository o esecuzioni di pipeline che la pipeline host può eseguire. Se è stato abilitato Proteggere l'accesso ai repository nelle pipeline YAML, il relativo ambito è limitato solo ai repository a cui si fa riferimento nell'esecuzione della pipeline.

Se il controllo deve accedere a risorse non correlate alle pipeline, ad esempio alle storie utente di Boards, è necessario concedere tali autorizzazioni alle identità di compilazione delle pipeline. Se il controllo può essere attivato da più progetti, assicurarsi che tutte le pipeline in tutti i progetti possano accedere alle risorse necessarie.

Rimandare una decisione ad Azure DevOps

L'implementazione del controllo deve usare la chiamata API REST Post Event per comunicare una decisione ad Azure Pipelines. Assicurarsi di specificare le proprietà seguenti:

• Headers: Bearer {AuthToken}
• Body:

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

Inviare aggiornamenti dello stato ad Azure DevOps dai controlli

È possibile fornire aggiornamenti dello stato agli utenti di Azure Pipelines dall'interno dei controlli usando le API REST di Azure Pipelines. Questa funzionalità è utile, ad esempio, se si vuole informare gli utenti che il controllo è in attesa di un'azione esterna, ad esempio un utente deve approvare un ticket ServiceNow.

I passaggi per inviare gli aggiornamenti dello stato sono i seguenti:

1. Creare un registro delle attività
2. Aggiungi al registro delle attività
3. Aggiornare il record della sequenza temporale

Tutte le chiamate API REST devono essere autenticate.

Esempi

Controllo di base della funzione di Azure

In questo esempio di base, la funzione di Azure verifica che la pipeline chiamante esegua un'attività CmdLine , prima di concedere l'accesso a una risorsa protetta.

La funzione di Azure esegue i passaggi seguenti:

1. Conferma la ricezione del carico utile della verifica
2. Invia un aggiornamento dello stato ad Azure Pipelines indicando che il controllo è iniziato
3. Usa {AuthToken} per effettuare un callback su Azure Pipelines per recuperare la voce della sequenza temporale dell'esecuzione della pipeline
4. Controlla se la sequenza temporale contiene un'attività con "id": "D9BAFED4-0B18-4F58-968D-86655B4D2CE9" (l'ID dell'attività CmdLine )
5. Invia un aggiornamento dello stato con il risultato della ricerca
6. Invia una decisione di controllo ad Azure Pipelines

È possibile scaricare questo esempio da GitHub.

Per usare questo controllo della funzione di Azure, è necessario specificare quanto segue Headers durante la configurazione del controllo:

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

Controllo avanzato delle funzioni di Azure

In questo esempio avanzato, la funzione di Azure verifica che l'elemento di lavoro di Azure Boards a cui fa riferimento nel messaggio di commit che ha attivato l'esecuzione della pipeline sia nello stato corretto.

La funzione di Azure esegue i passaggi seguenti:

1. Conferma la ricezione del carico utile della verifica
2. Invia un aggiornamento dello stato ad Azure Pipelines che indica l'inizio del controllo
3. {AuthToken} Usa per eseguire un callback in Azure Pipelines per recuperare lo stato dell'elemento di lavoro di Azure Boards a cui si fa riferimento nel messaggio di commit che ha attivato l'esecuzione della pipeline
4. Controlla se l'elemento di lavoro è nello Completed stato
5. Invia un aggiornamento dello stato con il risultato del controllo
6. Se l'elemento di lavoro non è nello stato Completed, riprogramma un'altra valutazione tra 1 minuto
7. Quando l'elemento di lavoro è nello stato corretto, invia una decisione positiva ad Azure Pipelines

È possibile scaricare questo esempio da GitHub.

Per usare questo controllo della funzione di Azure, è necessario specificare quanto segue Headers durante la configurazione del controllo:

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

Gestione degli errori

Attualmente, Azure Pipelines valuta un'istanza di controllo singola al massimo 2.000 volte.

Se il controllo non viene richiamato in Azure Pipelines entro il timeout configurato, la fase associata viene ignorata. Anche le fasi che dipendono da esso vengono ignorate.

Controlli sincroni

In modalità sincrona, Azure DevOps effettua una chiamata all'API REST/funzione di Azure per ottenere una decisione immediata se l'accesso a una risorsa protetta è consentito o meno.

L'implementazione della modalità di sincronizzazione per un singolo controllo della funzione di Azure è illustrata nel diagramma seguente.

I passaggi sono:

1. Azure Pipelines prepara la distribuzione di una fase della pipeline e richiede l'accesso a una risorsa protetta
2. Entra in un ciclo interno in cui:

• 2.1. Azure Pipelines richiama il controllo della funzione di Azure corrispondente e attende una decisione
• 2.2. La funzione di Azure valuta le condizioni necessarie per consentire l'accesso e restituisce una decisione
• 2.3. Se il corpo della risposta della funzione di Azure non soddisfa i criteri di esito positivo definiti e Il tempo tra le valutazioni è diverso da zero, Azure Pipelines riprogramma un'altra valutazione del controllo dopo il tempo tra le valutazioni

Configurare i controlli sincroni

Per usare la modalità sincrona per l'Azure Function / API REST, nel pannello di configurazione assicurarsi di:

• ApiResponse selezionata per l'evento Completamento in Avanzate
• Specificare i criteri di successo che definiscono quando superare il controllo in base al contenuto della risposta del controllo
• Impostare Tempo tra le valutazioni su 0 in Opzioni di controllo
• Impostare Timeout su per quanto tempo si desidera attendere il completamento di un controllo. Se non c'è una decisione positiva e viene raggiunto il timeout, la fase della pipeline corrispondente viene saltata.

L'impostazione Tempo tra valutazioni definisce per quanto tempo la decisione del controllo è valida. Un valore pari a 0 indica che la decisione è finale. Un valore diverso da zero indica che il controllo verrà ritentato dopo l'intervallo configurato, quando la decisione è negativa. Quando sono in esecuzione più approvazioni e controlli , il controllo viene ripetuto indipendentemente dalla decisione.

Il numero massimo di valutazioni è definito dal rapporto tra timeout e tempo tra i valori delle valutazioni. È consigliabile assicurarsi che questo rapporto sia al massimo 10.

Passare le informazioni sull'esecuzione della pipeline ai controlli

Quando si configura il controllo, è possibile specificare le informazioni sull'esecuzione della pipeline da inviare alla Funzione Azure / API REST di controllo. Per impostazione predefinita, Azure Pipeline aggiunge le informazioni seguenti nella Headers chiamata HTTP eseguita.

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

Non è consigliabile effettuare chiamate ad Azure DevOps in modalità sincrona, perché probabilmente il controllo richiede più di 3 secondi di risposta, in modo che il controllo abbia esito negativo.

Gestione degli errori

Attualmente, Azure Pipelines valuta un'istanza di controllo singola al massimo 2.000 volte.

Quando usare controlli asincroni e sincroni

Verranno ora esaminati alcuni casi d'uso di esempio e quali sono i tipi consigliati di controlli da usare.

Le informazioni esterne devono essere corrette

Si supponga di avere una connessione al servizio a una risorsa di produzione e di assicurarsi che l'accesso sia consentito solo se le informazioni in un ticket ServiceNow sono corrette. In questo caso, il flusso sarà il seguente:

• Si aggiunge un controllo asincrono di Funzioni di Azure che verifica la correttezza del ticket ServiceNow
• Quando una pipeline che vuole usare la Connessione di Servizio viene eseguita:
  • Azure Pipelines chiama la funzione di verifica
  • Se le informazioni non sono corrette, il controllo restituisce una decisione negativa. Assumi questo risultato
  • La fase della pipeline fallisce
  • Aggiornare le informazioni nel ticket ServiceNow
  • Si riavvia la fase non riuscita
  • Il controllo viene eseguito di nuovo e questa volta ha esito positivo
  • L'esecuzione della pipeline continua

È necessario concedere l'approvazione esterna

Si supponga di avere una connessione al servizio a una risorsa di produzione e di assicurarsi che l'accesso sia consentito solo dopo che un amministratore ha approvato un ticket ServiceNow. In questo caso, il flusso sarà il seguente:

• Si aggiunge un controllo asincrono di Funzioni di Azure che verifica che il ticket ServiceNow sia stato approvato
• Quando una pipeline che vuole usare la connessione al servizio viene eseguita:
  • Azure Pipelines chiama la funzione di verifica.
  • Se il ticket ServiceNow non è approvato, la funzione di Azure invia un aggiornamento ad Azure Pipelines e si riprogramma per controllare lo stato del ticket in 15 minuti
  • Dopo l'approvazione del ticket, il controllo richiama in Azure Pipelines con una decisione positiva
  • L'esecuzione della pipeline continua

È stato seguito il processo di sviluppo

Si supponga di avere una connessione al servizio a una risorsa di produzione e di assicurarsi che l'accesso a tale risorsa sia consentito solo se il code coverage è superiore all'80%. In questo caso, il flusso sarà il seguente:

• È possibile scrivere la pipeline in modo che gli errori di fase causi un errore di compilazione
• Si aggiunge una Funzione di Azure asincrona che verifica la copertura del codice per l'esecuzione della pipeline associata.
• Quando una pipeline che intende utilizzare la connessione al servizio viene eseguita:
  • Azure Pipelines chiama la funzione di verifica
  • Se la condizione di code coverage non viene soddisfatta, il controllo produce una decisione negativa. Si assuma questo risultato
  • Il fallimento del controllo causa il fallimento della fase, che a sua volta provoca il fallimento dell'esecuzione della pipeline.
• Il team di ingegneria aggiunge gli unit test necessari per raggiungere l'80% di copertura del codice.
• Viene attivata una nuova esecuzione della pipeline e questa volta il controllo viene superato.
  • L'esecuzione della pipeline continua

I criteri di prestazioni devono essere soddisfatti

Si supponga di distribuire nuove versioni del sistema in più passaggi, a partire da una distribuzione canary. Si desidera assicurarsi che le prestazioni dell'implementazione canary siano adeguate. In questo caso, il flusso sarà il seguente:

• Si aggiunge un controllo asincrono di Funzioni di Azure
• Quando viene eseguita una pipeline che vuole usare la connessione al servizio:
  • Azure Pipelines chiama la funzione "check"
  • Il controllo avvia un monitoraggio delle prestazioni della distribuzione canary
  • Il controllo pianifica diversi checkpoint di valutazione per vedere come sono evolute le prestazioni.
  • Una volta ottenuta sufficiente fiducia nelle prestazioni dell'implementazione Canary, la Funzione Azure richiama Azure Pipelines con una decisione positiva.
  • L'operazione della pipeline prosegue

Il motivo della distribuzione deve essere valido

Supponiamo che tu abbia una Service Connection a una risorsa dell'ambiente di produzione e desideri assicurarti che l'accesso avvenga solo per le build messe in coda manualmente. In questo caso, il flusso sarà il seguente:

• Si aggiunge un controllo della funzione di Azure sincrono che verifica che Build.Reason per l'esecuzione della pipeline sia Manual
• Tu configuri il controllo della funzione di Azure per passare Build.Reason nel suo Headers
• Hai impostato il tempo tra le valutazioni su 0, pertanto l'esito negativo o positivo è finale e non è necessaria una rivalutazione.
• Quando una pipeline che vuole usare la connessione al servizio viene eseguita:
  • Azure Pipelines chiama la funzione di verifica
  • Se il motivo è diverso da Manual, il controllo ha esito negativo e l'esecuzione della pipeline ha esito negativo

Controlli multipli

Prima che Azure Pipelines distribuisca una fase in un'esecuzione della pipeline, potrebbero essere necessari più controlli. A una risorsa protetta possono essere associati uno o più controlli. Una fase può usare più risorse protette. Azure Pipelines raccoglie tutti i controlli associati a ogni risorsa protetta usata in una fase e li valuta contemporaneamente.

Un'esecuzione della pipeline può essere distribuita in una fase solo quando tutti i controlli risultano superati contemporaneamente. Una singola decisione negativa finale fa sì che venga negato l'accesso alla pipeline e che la fase/stadio non riesca.

Quando si utilizzano i controlli nel modo consigliato (asincroni, con stati finali), questi rendono definitive le decisioni di accesso e facilitano la comprensione dello stato del sistema.

Per esempi, vedere la sezione Approvazioni e controlli multipli.

Altre informazioni

• Approvazioni e controlli
• Richiamare l'attività Funzione di Azure
• Attività Richiama API REST