Richiamare i controlli dell'API REST/funzione di Azure

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 l'implementazione dell'API REST/funzione di Azure per richiamare Azure DevOps con una decisione di accesso in fase
• Sincrona: modalità di polling, in cui Azure DevOps chiama periodicamente l'API REST/funzione di Azure per ottenere una decisione di accesso a fasi

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 del controllo. Azure Pipelines effettua una chiamata HTTP all'API REST/funzione di Azure solo per recapitare il payload di controllo e non per ricevere una decisione sul posto. 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, 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. È consigliabile usare la funzione di Azure seguendo questa procedura:
   • 2.1 Avviare un'attività asincrona e restituire il codice di stato HTTP 200
   • 2.2 Immettere un ciclo interno, in cui può eseguire più valutazioni delle 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

Quando si usa l'implementazione consigliata, la pagina dei dettagli dell'esecuzione della pipeline mostra il log di controllo più recente.

Configurazione consigliata per i controlli asincroni

Nel pannello di configurazione di controllo dell'API REST/funzione di Azure assicurarsi di:

• Callback selezionato per l'evento Completion
• Impostare Tempo tra valutazioni (minuti) su 0

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

Passare le informazioni sull'esecuzione della pipeline ai controlli

Quando si configura il controllo, è possibile specificare le informazioni sull'esecuzione della pipeline da inviare al controllo. È 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.

Chiamare Azure DevOps

Per prendere una decisione, il controllo potrebbe richiedere informazioni sull'esecuzione corrente della pipeline che non può essere passata al controllo, quindi il controllo deve recuperarlo. Si supponga che il controllo verifichi che un'esecuzione della pipeline esegua un'attività specifica, ad esempio un'attività di analisi statica. Il controllo 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 ai controlli per impostazione predefinita, nell'intestazione AuthToken .

Rispetto ai token di accesso al processo, il token di accesso al processo è meno soggetto a limitazione, non richiede l'aggiornamento manuale e non è associato a un account personale. Il token è valido per 48 ore.

Usando il token di accesso al processo, vengono rimossi tutti i problemi di limitazione dell'API REST di Azure DevOps. Quando si usa un token di accesso personale, si usa lo stesso pat per tutte le esecuzioni della pipeline. Se si esegue un numero elevato di pipeline, il pat viene limitato. Questo è meno un problema con il token di accesso al processo perché viene generato un nuovo token per ogni esecuzione del controllo.

Il token viene rilasciato per l'identità di compilazione usata 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 correlate non pipeline, ad esempio storie utente 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.

Inviare una decisione ad Azure DevOps

L'implementazione del controllo deve usare la chiamata ALL'API REST post-evento 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 log attività
2. Aggiungere al log 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 payload del controllo
2. Invia un aggiornamento dello stato ad Azure Pipelines avviato dal controllo
3. Usa {AuthToken} per eseguire un callback in Azure Pipelines per recuperare la voce 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 payload del controllo
2. Invia un aggiornamento dello stato ad Azure Pipelines avviato dal 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 Completed stato, riprogramma un'altra valutazione in 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 a seconda di 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'API REST/funzione di Azure, nel pannello di configurazione controllare assicurarsi di:

• Api SelezionataResponse per l'evento Completamento in Avanzate
• Specificare i criteri di esito positivo che definiscono quando passare il controllo in base al corpo 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 è presente alcuna decisione positiva e viene raggiunto il timeout , la fase della pipeline corrispondente viene ignorata

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 al controllo dell'API REST/funzione di Azure. 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 al servizio viene eseguita:
  • Azure Pipelines chiama la funzione check
  • Se le informazioni non sono corrette, il controllo restituisce una decisione negativa. Si supponga che questo risultato
  • La fase della pipeline ha esito negativo
  • 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 check.
  • 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 un controllo asincrono di Funzioni di Azure che verifica il code coverage per l'esecuzione della pipeline associata
• Quando una pipeline che vuole usare la connessione al servizio viene eseguita:
  • Azure Pipelines chiama la funzione check
  • Se la condizione di code coverage non viene soddisfatta, il controllo restituisce una decisione negativa. Si supponga che questo risultato
  • L'errore di controllo causa l'esito negativo della fase, causando l'esito negativo dell'esecuzione della pipeline
• Il team di progettazione aggiunge gli unit test necessari per raggiungere l'80% di code coverage
• Viene attivata una nuova esecuzione della pipeline e questa volta il controllo passa
  • 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 vuole assicurarsi che le prestazioni della distribuzione canary siano adeguate. In questo caso, il flusso sarà il seguente:

• Si aggiunge un controllo asincrono di Funzioni di Azure
• Quando una pipeline che vuole usare la connessione al servizio viene eseguita:
  • Azure Pipelines chiama la funzione check
  • Il controllo avvia un monitoraggio delle prestazioni della distribuzione canary
  • Il controllo pianifica più checkpoint di valutazione, per vedere come si è evoluto il rendimento
  • Una volta ottenuta una sufficientemente fiducia nelle prestazioni della distribuzione canary, la funzione di Azure richiama azure Pipelines con una decisione positiva
  • L'esecuzione della pipeline continua

Il motivo della distribuzione deve essere valido

Si supponga di avere una connessione al servizio a una risorsa di ambiente di produzione e di assicurarsi che l'accesso avvenga solo per le compilazioni 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
• Configurare il controllo della funzione di Azure per passarne Build.ReasonHeaders
• Impostare Il tempo del controllo tra le valutazioni su 0, quindi l'esito negativo o il passaggio è finale e non è necessaria alcuna rivalutazione
• Quando una pipeline che vuole usare la connessione al servizio viene eseguita:
  • Azure Pipelines chiama la funzione check
  • Se il motivo è diverso da Manual, il controllo ha esito negativo e l'esecuzione della pipeline ha esito negativo

Controlla conformità

Richiamare i controlli dell'API REST e della funzione di Azure ora includono regole per trovare le corrispondenze con l'utilizzo consigliato. I controlli devono seguire queste regole a seconda della modalità e del numero di tentativi:

• Controlli asincroni (modalità callback): Azure Pipelines non ritenta i controlli asincroni. È consigliabile fornire un risultato in modo asincrono quando una valutazione è finale. Affinché i controlli asincroni siano considerati conformi, l'intervallo di tempo tra le valutazioni deve essere 0.

• Controlli sincroni (modalità ApiResponse): il numero massimo di tentativi per il controllo è 10. È possibile impostare in diversi modi. Ad esempio, è possibile configurare il timeout su 20 e l'intervallo di tempo tra valutazioni e 2. In alternativa, è possibile configurare il timeout su 100 e l'intervallo di tempo tra valutazioni e 10. Tuttavia, se si configura il timeout su 100 e si imposta l'intervallo di tempo tra le valutazioni su 2, il controllo non sarà conforme perché la richiesta di 50 tentativi. Il rapporto tra timeout e intervallo di tempo tra le valutazioni deve essere minore o uguale a 10.

Altre informazioni sull'implementazione della verifica della conformità.

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 vengono superati contemporaneamente. Una singola decisione negativa finale fa sì che la pipeline venga negata e che la fase non riesca.

Quando si usano controlli nel modo consigliato (asincrono, con gli stati finali) prende le decisioni di accesso finali e semplifica 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à Invoke REST API (Richiama API REST)