Integrazione degli strumenti di creazione, test e distribuzione con Code Stream

In qualità di amministratore o di sviluppatore di DevOps, è possibile creare script personalizzati che estendano la funzionalità di Code Stream.

Grazie allo script, è possibile integrare Code Stream con gli strumenti di integrazione continua (CI) e di consegna continua (CD), nonché con le API che creano, testano e distribuiscono le applicazioni. Gli script personalizzati sono particolarmente utili se le API dell'applicazione non vengono esposte pubblicamente.

Lo script personalizzato può svolgere quasi tutte le operazioni necessarie per l'integrazione degli strumenti di creazione, test e distribuzione con Code Stream. Ad esempio, lo script può interagire con l'area di lavoro della pipeline per supportare le attività di integrazione continua che creano e testano l'applicazione e le attività di consegna continua che la distribuiscono. Può inviare un messaggio a Slack quando una pipeline termina e molto altro.

L'area di lavoro della pipeline di Code Stream supporta Docker e Kubernetes per le attività di integrazione continua e le attività personalizzate.

Per ulteriori informazioni sulla configurazione dell'area di lavoro, vedere Configurazione dell'area di lavoro della pipeline.

È possibile scrivere lo script personalizzato in uno dei linguaggi supportati. Nello script è necessario includere la logica di business e definire input e output. I tipi di output possono includere numero, stringa, testo e password. È possibile creare più versioni di uno script personalizzato con logica di business, input e output diversi.

Gli script creati si trovano nell'istanza di Code Stream. È possibile importare codice YAML per creare un'integrazione personalizzata o esportare lo script come file YAML da utilizzare in un'altra istanza di Code Stream.

È necessario che la pipeline esegua una versione rilasciata dello script in un'attività personalizzata. Se sono presenti più versioni rilasciate, è possibile impostarne una come più recente in modo che venga visualizzata con più recente --> quando si seleziona l'attività personalizzata.

Quando una pipeline utilizza un'integrazione personalizzata, se si tenta di eliminare l'integrazione personalizzata, viene visualizzato un messaggio di errore che indica che non è possibile eliminarla.

L'eliminazione di un'integrazione personalizzata comporta la rimozione di tutte le versioni dello script personalizzato. Se esiste una pipeline con un'attività personalizzata che utilizza una versione qualsiasi dello script, la pipeline non riuscirà. Per assicurarsi che le pipeline esistenti vengano eseguite correttamente, è possibile deprecare e ritirare la versione dello script che non si desidera più utilizzare. Se tale versione non viene utilizzata da alcuna pipeline, è possibile eliminarla.

Tabella 1. Cosa fare dopo aver scritto lo script personalizzato
Cosa fare...	Ulteriori informazioni su questa azione...
Aggiungere un'attività personalizzata alla pipeline.	L'attività personalizzata: Viene eseguita nello stesso contenitore di altre attività CI nella pipeline. Include le variabili di input e output che lo script popola prima che la pipeline esegua l'attività personalizzata. Supporta più tipi di dati e vari tipi di metadati che vengono definiti come input e output nello script.
Selezionare lo script nell'attività personalizzata.	Le proprietà di input e output vengono dichiarate nello script.
Salvare la pipeline, quindi abilitarla ed eseguirla.	Quando la pipeline è in esecuzione, l'attività personalizzata richiama la versione dello script specificata e con tale versione esegue la logica di business, che integra lo strumento di creazione, test e distribuzione con Code Stream.
Una volta eseguita la pipeline, esaminare le esecuzioni.	Verificare che la pipeline abbia fornito i risultati previsti.

Quando si utilizza un'attività personalizzata che richiama una versione di Integrazione personalizzata, è possibile includere variabili di ambiente personalizzate come coppie nome-valore nella scheda Area di lavoro della pipeline. Quando l'immagine del generatore crea il contenitore dell'area di lavoro che esegue l'attività CI e distribuisce l'immagine, Code Stream passa le variabili di ambiente a tale contenitore.

Ad esempio, quando l'istanza di Code Stream richiede un proxy Web e si utilizza un host Docker per creare un contenitore per un'integrazione personalizzata, Code Stream esegue la pipeline e passa le variabili di impostazione del proxy Web a tale contenitore.

Tabella 2. Esempio di coppie nome-valore delle variabili di ambiente
Nome	Valore
HTTPS_PROXY	http://10.0.0.255:1234
https_proxy	http://10.0.0.255:1234
NO_PROXY	10.0.0.32, *.dept.vsphere.local
no_proxy	10.0.0.32, *.dept.vsphere.local
HTTP_PROXY	http://10.0.0.254:1234
http_proxy	http://10.0.0.254:1234
PATH	/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Le coppie nome-valore vengono visualizzate nell'interfaccia utente nel modo seguente:

Code Stream passa le variabili di ambiente al contenitore creato dall'immagine del generatore.

In questo esempio viene creata un'integrazione personalizzata che connette Code Stream all'istanza di Slack e invia un messaggio a un canale Slack.

Prerequisiti

Per scrivere lo script personalizzato, verificare di disporre di uno di questi linguaggi: Python 2, Python 3, Node.js o di uno di questi linguaggi della shell: Bash, sh o zsh.
Generare un'immagine del contenitore utilizzando il runtime Node.js o Python installato.

Procedura

Creare l'integrazione personalizzata.

Fare clic su Integrazioni personalizzate > Nuovo e immettere un nome pertinente.
Selezionare l'ambiente di runtime preferito.
Fare clic su Crea.
Lo script si apre e viene visualizzato il codice, che include l'ambiente di runtime richiesto. Ad esempio runtime: "nodejs". Lo script deve includere il runtime, utilizzato dall'immagine del generatore, in modo che l'attività personalizzata aggiunta alla pipeline venga eseguita correttamente quando viene eseguita la pipeline. In caso contrario, l'attività personalizzata non riesce.

Le aree principali dello YAML dell'integrazione personalizzata includono runtime, codice, proprietà di input e proprietà di output. Questa procedura illustra diversi tipi e sintassi.


Chiavi YAML dell'integrazione personalizzata	Descrizione
runtime	Ambiente di runtime dell'attività in cui Code Stream esegue il codice, che può essere una di queste stringhe senza distinzione tra maiuscole e minuscole: nodejs python2 python3 shell Se non viene specificato alcun valore, viene utilizzato shell per impostazione predefinita.
code	Logica di business personalizzata da eseguire come parte dell'attività personalizzata.
inputProperties	Array di proprietà di input da acquisire come parte della configurazione dell'attività personalizzata. Queste proprietà vengono in genere utilizzate nel codice.
outputProperties	Array di proprietà di output che è possibile esportare dall'attività personalizzata da propagare alla pipeline.

Dichiarare le proprietà di input nello script utilizzando i tipi di dati e i metadati disponibili.

Le proprietà di input vengono passate come contesto allo script nella sezione code: del linguaggio YAML.


Chiavi di input YAML per l'attività personalizzata	Descrizione	Obbligatoria
`type`	Tipi di input per il rendering: `text` `textarea` `number` `checkbox` `password` `select`	Sì
`name`	Nome o stringa dell'input per l'attività personalizzata, che viene inserito nel codice YAML dell'integrazione personalizzata. Deve essere univoco per ogni proprietà di input definita per un'integrazione personalizzata.	Sì
`title`	Etichetta della stringa di testo della proprietà di input per l'attività personalizzata nella tela del modello di pipeline. Se viene lasciata vuota, per impostazione predefinita viene utilizzato il valore `name`.	No
`required`	Determina se un utente deve immettere la proprietà di input quando configura l'attività personalizzata. Impostare su true o su false. Quando è true, se un utente non specifica alcun valore quando configura l'attività personalizzata nella tela della pipeline, lo stato dell'attività rimane non configurata.	No
`placeHolder`	Testo predefinito per l'area di immissione della proprietà di input quando non è presente alcun valore. Viene mappato all'attributo placeholder HTML. Supportata solo per determinati tipi di proprietà di input.	No
`defaultValue`	Valore predefinito che popola l'area di immissione della proprietà di input quando viene eseguito il rendering dell'attività personalizzata nella pagina del modello di pipeline.	No
`bindable`	Determina se la proprietà di input accetta le variabili con simbolo di dollaro quando si modella l'attività personalizzata nella tela della pipeline. Aggiunge l'indicatore $ accanto al titolo. Supportata solo per determinati tipi di proprietà di input.	No
`labelMessage`	Stringa che funge da descrizione comando della guida per gli utenti. Aggiunge un'icona descrizione comando i accanto al titolo di input.	No
`enum`	Acquisisce un array di valori che visualizza le opzioni delle proprietà di input selezionate. Supportata solo per determinati tipi di proprietà di input. Quando un utente seleziona un'opzione e la salva per l'attività personalizzata, il valore di inputProperty corrisponde a questo valore e viene visualizzato nella modellazione dell'attività personalizzata. Ad esempio, il valore 2015. 2015 2016 2017 2018 2019 2020	No
`options`	Acquisisce un array di oggetti utilizzando optionKey e optionValue. optionKey. Valore propagato alla sezione del codice dell'attività. optionValue. Stringa che visualizza l'opzione nell'interfaccia utente. Supportata solo per determinati tipi di proprietà di input. Opzioni: optionKey: key1. Quando viene selezionata e salvata per l'attività personalizzata, il valore di questa proprietà inputProperty corrisponde a key1 nella sezione del codice. optionValue: 'Etichetta per 1'. Valore visualizzato per key1 nell'interfaccia utente. Non viene visualizzato in alcun altro punto per l'attività personalizzata. optionKey: key2 optionValue: 'Etichetta per 2' optionKey: key3 optionValue: 'Etichetta per 3'	No
`minimum`	Acquisisce un numero che funge da valore minimo valido per questa proprietà di input. Supportata solo per la proprietà di input di tipo number.	No
`maximum`	Acquisisce un numero che funge da valore massimo valido per questa proprietà di input. Supportata solo per la proprietà di input di tipo number.	No

Tabella 3. Metadati e tipi di dati supportati per script personalizzati
Tipi di dati supportati	Metadati supportati per l'input
Stringa Testo Elenco: come elenco di qualsiasi tipo Mappa: come map[string]any Sicuri: rappresentati come casella di testo per la password, crittografati quando si salva l'attività personalizzata Numero Booleani: visualizzati come caselle di testo URL: come stringa, con convalida aggiuntiva Selezione, pulsante di opzione	type: Stringa \| Testo... default: valore predefinito options: elenco o mappa di opzioni da utilizzare con la selezione o il pulsante di opzione min: valore o dimensione minimi max: valore o dimensione massimi title: nome dettagliato della casella di testo placeHolder: segnaposto dell'interfaccia utente description: diventa una descrizione comando

Ad esempio:

inputProperties:
        - name: message
          type: text
          title: Message
          placeHolder: Message for Slack Channel
          defaultValue: Hello Slack
          bindable: true
          labelInfo: true
          labelMessage: This message is posted to the Slack channel link provided in the code

Dichiarare le proprietà di output nello script.

Lo script acquisisce le proprietà di output dalla sezione code: della relativa business logic, dove si dichiara il contesto per l'output.

Quando la pipeline viene eseguita, è possibile immettere il codice di risposta per l'output dell'attività. Ad esempio 200.

Chiavi che Code Stream supporta per ogni outputProperty.


Chiave	Descrizione
type	Attualmente include un singolo valore di `label`.
nome	Chiave emessa dal blocco di codice dello YAML dell'integrazione personalizzata.
title	Etichetta nell'interfaccia utente che visualizza outputProperty.

Ad esempio:

outputProperties:
  - name: statusCode
    type: label
    title: Status Code

Per interagire con l'input e l'output dello script personalizzato, recuperare una proprietà di input o impostare una proprietà di output utilizzando context.

Per una proprietà di input: (context.getInput("key"))

Per una proprietà di output: (context.setOutput("key", "value"))

Per Node.js:

var context = require("./context.js")
var message = context.getInput("message");
//Your Business logic
context.setOutput("statusCode", 200);

Per Python:

from context import getInput, setOutput
message = getInput('message')
//Your Business logic
setOutput('statusCode', '200')

Per Shell:

# Input, Output properties are environment variables
echo ${message} # Prints the input message
//Your Business logic
export statusCode=200 # Sets output property statusCode

Nella sezione code: dichiarare tutta la logica di business per l'integrazione personalizzata.

Ad esempio, con l'ambiente di runtime Node.js:

code: |
    var https = require('https');
    var context = require("./context.js")
    
    //Get the entered message from task config page and assign it to message var
    var message = context.getInput("message");
    var slackPayload = JSON.stringify(
        {
            text: message
        });

    const options = {
        hostname: 'hooks.slack.com',
        port: 443,
        path: '/YOUR_SLACK_WEBHOOK_PATH',
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Content-Length': Buffer.byteLength(slackPayload)
        }
    };
    
    // Makes a https request and sets the output with statusCode which 
    // will be displayed in task result page after execution
    const req = https.request(options, (res) => {
        context.setOutput("statusCode", res.statusCode);
    });

    req.on('error', (e) => {
        console.error(e);
    });
    req.write(slackPayload);
    req.end();

Prima di eseguire la versione e rilasciare lo script di integrazione personalizzato, scaricare il file di contesto per Python o Node.js e verificare la logica di business inclusa nello script.
1. Posizionare il puntatore nella parte superiore della tela e fare clic sul pulsante del file di contesto. Ad esempio, se lo script è in linguaggio Python fare clic su CONTEXT.PY.
2. Modificare il file e salvarlo.
3. Nel sistema di sviluppo eseguire e testare lo script personalizzato con l'aiuto del file di contesto.
Applicare una versione allo script di integrazione personalizzato.
1. Fare clic su Versione.
2. Inserire le informazioni sulla versione.
3. Fare clic su Versione di rilascio per poter selezionare lo script nell'attività personalizzata.
4. Per creare la versione, fare clic su Crea.
(Facoltativo) È possibile impostare una versione rilasciata di uno script di integrazione personalizzato come versione più recente in modo che la versione venga visualizzata con l'etichetta più recente --> nella tela della pipeline.
1. Posizionare il puntatore nella parte superiore della tela e fare clic su Cronologia versione.
2. Per visualizzare le azioni disponibili, fare clic sui puntini di sospensione orizzontali per la versione desiderata e selezionare Imposta come più recente.
  
  Nota: Solo le versioni rilasciate vengono visualizzate con l'azione Imposta come più recente.
3. Per confermare la selezione della versione, fare clic su Imposta come più recente.
4. Per uscire da Cronologia versioni e tornare alla tela dell'editor di script, fare clic sulla freccia indietro.
Per salvare lo script, fare clic su Salva.
Per esportare lo script come file YAML da utilizzare in un'altra istanza Code Stream, fare clic su Azioni > Esporta nella scheda di integrazione personalizzata e selezionare le versioni da esportare.
Nella pipeline, configurare l'area di lavoro.
Questo esempio utilizza un'area di lavoro di Docker.
1. Fare clic sulla scheda Area di lavoro.
2. Selezionare l'host Docker e l'URL immagine generatore.
Aggiungere un'attività personalizzata alla pipeline e configurarla.
1. Fare clic sulla scheda Modello.
2. Aggiungere un'attività, selezionare il tipo come Personalizzato e immettere un nome pertinente.
3. Selezionare lo script di integrazione personalizzato e la versione. Se una versione dello script è stata impostata come più recente, tale versione viene visualizzata con più recente --> prima del nome della versione.
4. Per visualizzare un messaggio personalizzato in Slack, immettere il testo del messaggio.
  Il testo immesso sostituisce defaultValue nello script di integrazione personalizzato.
Salvare e abilitare la pipeline.
1. Fare clic su Salva.
2. Nella scheda della pipeline, fare clic su Azioni > Abilita.
Eseguire la pipeline.
1. Fare clic su Esegui.
2. Osservare l'esecuzione della pipeline.
3. Verificare che l'output includa il codice di stato, il codice di risposta, lo stato e l'output dichiarato previsti.
  È stato definito statusCode come proprietà di output. Ad esempio, uno statusCode di 200 potrebbe indicare un post creato correttamente in Slack e un responseCode di 0 potrebbe indicare che lo script è riuscito senza errori.
4. Per verificare l'output nei registri di esecuzione, fare clic su Esecuzioni, fare clic sul collegamento alla pipeline, quindi sull'attività e controllare i dati registrati. Ad esempio:
Se si verifica un errore, risolvere il problema ed eseguire nuovamente la pipeline.
Ad esempio, se manca un file o un modulo nell'immagine di base, è necessario creare un'altra immagine di base che includa il file mancante. Quindi specificare il file Docker e inserire l'immagine attraverso la pipeline.

risultati

Congratulazioni! È stato creato uno script di integrazione personalizzata che connette Code Stream all'istanza di Slack e invia un messaggio a un canale Slack.

Operazioni successive

Continuare a creare integrazioni personalizzate per supportare l'utilizzo di attività personalizzate nelle pipeline, in modo da poter estendere la funzionalità di Code Stream nell'automazione del ciclo di vita del rilascio del software.