Hoe kan ik mijn eigen tools voor bouwen, testen en implementeren integreren met Code Stream?

Als DevOps-beheerder of -ontwikkelaar kunt u custom scripts maken om de mogelijkheden van Code Stream uit te breiden.

Met uw script kunt u Code Stream integreren met uw eigen tools voor continue integratie (CI) en continue levering (CD) en API's die uw applicaties bouwen, testen en implementeren. Custom scripts zijn vooral handig als u de API's van de applicatie niet openbaar weergeeft.

Uw aangepast script kan bijna alles doen wat u nodig heeft voor uw tools voor bouwen, testen en implementeren om te integreren met Code Stream. Uw script kan bijvoorbeeld samenwerken met uw pijplijnwerkplek om ondersteuning te bieden voor taken voor continue integratie te ondersteunen die uw applicatie bouwen en testen, en voor taken voor continue levering die uw applicatie implementeren. Het kan een bericht verzenden naar Slack wanneer een pijplijn is voltooid en nog veel meer.

De Code Stream-pijplijnwerkplek ondersteunt Docker en Kubernetes voor taken voor continue integratie en aangepaste taken.

Zie De pijplijnwerkplek configureren voor meer informatie over het configureren van de werkplek.

U schrijft uw custom script in een van de ondersteunde talen. In het script neemt u uw bedrijfslogica op en definieert u de input en output. Outputtypen kunnen onder meer getal, tekenreeks, tekst en wachtwoord zijn. U kunt meerdere versies van een custom script maken met verschillende bedrijfslogica, invoer en uitvoer.

De scripts die u maakt, bevinden zich in uw Code Stream-instantie. U kunt YAML-code importeren om een aangepaste integratie te maken of uw script als YAML-bestand exporteren voor gebruik in een andere Code Stream-instantie.

U laat uw pijplijn een vrijgegeven versie van uw script in een aangepaste taak uitvoeren. Als u meerdere vrijgegeven versies heeft, kunt u een van deze versies instellen als nieuwste versie zodat het met nieuwste --> wordt weergegeven wanneer u de aangepaste taak selecteert.

Wanneer een pijplijn een custom integratie gebruikt, wordt een foutbericht weergegeven en wordt aangegeven dat u het niet kunt verwijderen als u de custom integratie probeert te verwijderen.

Als u een custom integratie verwijdert, worden alle versies van uw custom script verwijderd. Als u een bestaande pijplijn heeft met een custom taak die een willekeurige versie van het script gebruikt, zal deze pijplijn mislukken. Om ervoor te zorgen dat bestaande pijplijnen niet mislukken, kunt u de versie van uw script die u niet langer wilt gebruiken, afkeuren en intrekken. Als geen pijplijn die versie gebruikt, kunt u deze verwijderen.

Tabel 1. Wat u doet nadat u het custom script heeft geschreven
Wat u doet…	Meer informatie over deze actie…
Voeg een custom taak toe aan uw pijplijn.	De custom taak: wordt uitgevoerd op dezelfde container als andere CI-taken in uw pijplijn. bevat input- en outputvariabelen die door uw script worden gevuld voordat de pijplijn de custom taak uitvoert. ondersteunt meerdere gegevenstypen en verschillende typen metagegevens die u definieert als input en output in uw script.
Selecteer uw script in de custom taak.	U declareert de input- en outputproperties in het script.
Sla de pijplijn op. Vervolgens schakelt u de pijplijn in en voert u deze uit.	Wanneer de pijplijn wordt uitgevoerd, roept de custom taak de versie van de gespecificeerde script aan en voert het de bedrijfslogica erin uit die uw tool voor bouwen, testen en implementeren met Code Stream integreert.
Bekijk de uitvoeringen nadat uw pijplijn is uitgevoerd.	Controleer of de pijplijn de verwachte resultaten heeft geleverd.

Wanneer u een aangepaste taak gebruikt die een versie van de aangepaste integratie aanroept, kunt u aangepaste omgevingsvariabelen als naam-waardeparen opnemen op het tabblad Workspace van de pijplijn. Wanneer de image van de opbouwfunctie de Workspace-container maakt die de CI-taak uitvoert en uw image implementeert, worden de omgevingsvariabelen door Code Stream doorgegeven aan die container.

Wanneer uw Code Stream-instantie bijvoorbeeld een webproxy vereist en u een Docker-host gebruikt om een container voor een aangepaste integratie te maken, wordt de pijplijn door Code Stream uitgevoerd en worden de variabelen van de webproxyinstelling doorgegeven aan die container.

Tabel 2. Voorbeeld van naam-waardeparen voor omgevingsvariabelen
Naam	Waarde
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
PAD	/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

Naam-waardeparen worden als volgt weergegeven in de gebruikersinterface:

Code Stream geeft de omgevingsvariabelen door aan de container die de builderimage maakt.

Dit voorbeeld maakt een custom integratie die Code Stream verbindt met uw Slack-instantie en een bericht op een Slack-kanaal plaatst.

Voorwaarden

Verifieer voor het schrijven van een aangepast script of u een van deze talen heeft: Python 2, Python 3, Node.js of een van de Shell-talen: Bash, sh of zsh.
Genereer een containerimage met behulp van de geïnstalleerde Node.js of de Python-runtime.

Procedure

Maak de custom integratie.

Klik op Custom integraties > Nieuw en voer een relevante naam in.
Selecteer de gewenste runtimeomgeving.
Klik op Maken.
Uw script wordt geopend en toont de code, die de vereiste runtimeomgeving omvat. Bijvoorbeeld: runtime: "nodejs". Het script moet de runtime bevatten, die door de builderimage wordt gebruikt, zodat de custom taak die u aan uw pijplijn toevoegt, slaagt wanneer de pijplijn wordt uitgevoerd. Anders mislukt de custom taak.

De belangrijkste gebieden van uw custom integratie-YAML zijn onder meer de runtime, code, invoereigenschappen en uitvoereigenschappen. In deze procedure worden verschillende typen en syntaxis uitgelegd.


YAML-sleutels voor custom integratie	Beschrijving
runtime	Taakruntimeomgeving waarin Code Stream de code uitvoert. Dit kan een van de volgende hoofdlettergevoelige tekenreeksen zijn: nodejs python2 python3 shell Als er niets wordt opgegeven, is shell de veronderstelde standaardwaarde.
code	Custom bedrijfslogica die wordt uitgevoerd als onderdeel van de custom taak.
inputProperties	Reeks invoereigenschappen die moeten worden vastgelegd als onderdeel van de configuratie van de custom taak. Deze eigenschappen worden normaal gesproken gebruikt in de code.
outputProperties	Reeks uitvoereigenschappen die u kunt exporteren vanaf de custom taak om door te geven aan de pijplijn.

Declareer de inputproperties in uw script met behulp van de beschikbare gegevenstypen en metagegevens.

De inputproperties worden als context doorgegeven aan uw script in het code:-gedeelte van de YAML.


YAML-invoersleutels voor custom taak	Beschrijving	Vereist
`type`	Invoertypen om te renderen: `text` `textarea` `number` `checkbox` `password` `select`	Ja
`name`	Naam of tekenreeks van de invoer voor de custom taak, die wordt geïnjecteerd in de YAML-code voor de custom integratie. Moet uniek zijn voor elke invoereigenschap die voor een custom integratie is gedefinieerd.	Ja
`title`	Teksttekenreekslabel van de invoereigenschap voor de custom taak op het pijplijnmodelcanvas. Als dit veld leeg blijft, wordt `name` standaard gebruikt.	Nee
`required`	Bepaalt of een gebruiker de invoereigenschap moet invoeren wanneer hij de custom taak configureert. Stel in op waar of onwaar. Indien waar, als een gebruiker geen waarde opgeeft wanneer hij de custom taak op het pijplijncanvas configureert, blijft de status van de taak ongeconfigureerd.	Nee
`placeHolder`	Standaardtekst voor het veld van de invoereigenschap als er geen waarde aanwezig is. Wordt toegewezen aan het kenmerk voor de tijdelijke HTML-aanduiding. Wordt alleen ondersteund voor bepaalde typen invoereigenschappen.	Nee
`defaultValue`	Dit is de standaardwaarde die het veld van de invoereigenschap vult wanneer de custom taak wordt weergegeven op de pijplijnmodelpagina.	Nee
`bindable`	Bepaalt of de invoereigenschap dollartekenvariabelen accepteert bij het modelleren van de custom taak op het pijplijncanvas. Hiermee voegt u de $-indicator naast de titel toe. Wordt alleen ondersteund voor bepaalde typen invoereigenschappen.	Nee
`labelMessage`	Tekenreeks die fungeert als hulpknopinfo voor gebruikers. Voegt een pictogram voor knopinfo i toe naast de titel van de invoer.	Nee
`enum`	Haalt een reeks waarden op die de opties voor het selecteren van de invoereigenschap weergeven. Alleen ondersteund voor bepaalde typen invoereigenschappen. Wanneer een gebruiker een optie selecteert en deze opslaat voor de custom taak, komt de waarde van inputProperty overeen met deze waarde en wordt deze weergegeven in de custom taakmodellering. Bijvoorbeeld: de waarde 2015. 2015 2016 2017 2018 2019 2020	Nee
`options`	Neemt een reeks objecten met behulp van optionKey en optionValue. optionKey. Waarde die is doorgegeven aan het codegedeelte van de taak. optionValue. Tekenreeks die de optie in de gebruikersinterface weergeeft. Alleen ondersteund voor bepaalde typen invoereigenschappen. Opties: optionKey: key1. De waarde van deze inputProperty komt overeen met key1 in de codesectie wanneer deze is geselecteerd en opgeslagen voor de aangepaste taak. optionValue: 'Label for 1'. Weergegeven waarde weer voor key1 in de gebruikersinterface. Deze wordt nergens anders weergegeven voor de custom taak. optionKey: key2 optionValue: 'Label for 2' optionKey: key3 optionValue: 'Label for 3'	Nee
`minimum`	Heeft een getal dat fungeert als de minimumwaarde die geldig is voor deze invoereigenschap. Wordt alleen ondersteund voor de invoereigenschap van het type getal.	Nee
`maximum`	Heeft een getal dat fungeert als de maximumwaarde die geldig is voor deze invoereigenschap. Wordt alleen ondersteund voor de invoereigenschap van het type getal.	Nee

Tabel 3. Ondersteunde gegevenstypen en metagegevens voor custom scripts
Ondersteunde gegevenstypen	Ondersteunde metagegevens voor input
Tekenreeks Tekst Lijst: als een lijst van een willekeurig type Kaart: als map[string]any Veilig: weergegeven als tekstvak voor wachtwoord, versleuteld wanneer u de custom taak opslaat Getal Boole: wordt weergegeven als tekstvakken URL: hetzelfde als tekenreeks, met aanvullende validatie Selectie, keuzerondje	type: Een van Tekenreeks \| Tekst … standaard: Standaardwaarde opties: Lijst of een kaart met opties, die moeten worden gebruikt met selectie of keuzerondje min: Minimum waarde of grootte max.: Maximum waarde of grootte titel: Gedetailleerde naam van het tekstvak tijdelijke aanduiding: tijdelijke aanduiding voor UI beschrijving: wordt een knopinfo

Bijvoorbeeld:

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

Declareer de outputproperties in uw script.

In het script worden outputproperties vastgelegd uit het code:-gedeelte met bedrijfslogica van uw script, waar u de context voor de output declareert.

Wanneer de pijplijn wordt uitgevoerd, kunt u de responscode voor de taakoutput invoeren. Bijvoorbeeld 200.

Sleutels die door Code Stream worden ondersteund voor elke outputProperty.


sleutel	Beschrijving
type	Bevat momenteel een enkele waarde voor `label`.
name	Sleutel die het codeblok van de custom integratie-YAML afgeeft.
title	Label in de gebruikersinterface die outputProperty weergeeft.

Bijvoorbeeld:

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

Als u wilt communiceren met de input en output van uw custom script, haalt u een inputproperty op of stelt u een outputproperty in met behulp van context.

Voor een inputproperty: (context.getInput("key"))

Voor een outputproperty: (context.setOutput("key", "value"))

Voor Node.js:

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

Voor Python:

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

Voor Shell:

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

In het code:-gedeelte declareert u alle bedrijfslogica voor uw custom integratie.

Bijvoorbeeld, in de runtimeomgeving van 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();

Download het contextbestand voor Python of Node.js en test de bedrijfslogica die u in het script heeft opgenomen voordat u het custom integratiescript versioneert en vrijgeeft.
1. Plaats de aanwijzer bovenaan het canvas en klik vervolgens op de knop voor het contextbestand. U klikt bijvoorbeeld, als uw script in Python is, op CONTEXT.PY.
2. Pas het bestand aan en sla het op.
3. Voer in uw ontwikkelingssysteem uw custom script uit en test het met behulp van het contextbestand.
Pas een versie toe op uw custom integratiescript.
1. Klik op Versie.
2. Voer de versiegegevens in.
3. Klik op Versie vrijgeven, zodat u het script in uw custom taak kunt selecteren.
4. Als u de versie wilt maken, klikt u op Maken.
(Optioneel) U kunt elke vrijgegeven versie van een aangepast integratiescript instellen als de nieuwste, zodat de versie wordt weergegeven met het label nieuwste --> op het pijplijncanvas.
1. Plaats de aanwijzer bovenaan het canvas en klik vervolgens op Versiegeschiedenis.
2. Als u beschikbare acties wilt zien, klikt u op de horizontale puntjes van de gewenste versie en selecteert u Instellen als nieuwste.
  
  Opmerking: Alleen vrijgegeven versies worden weergegeven met de actie Instellen als nieuwste.
3. Klik op Instellen als nieuwste om de versieselectie te bevestigen.
4. Als u Versiegeschiedenis wilt afsluiten en wilt terugkeren naar het canvas van de scripteditor, klikt u op de pijl terug.
Klik op Opslaan om het script op te slaan.
Als u uw script als YAML-bestand wilt exporteren voor gebruik in een andere Code Stream-instantie, klikt u op Acties > Exporteren op de aangepaste integratiekaart en selecteert u de versies die u wilt exporteren.
Configureer de werkplek in uw pijplijn.
In dit voorbeeld wordt een Docker-werkplek gebruikt.
1. Klik op het tabblad Werkruimte.
2. Selecteer de Docker-host en de builderimage-URL.
Voeg een custom taak toe aan uw pijplijn en configureer deze.
1. Klik op het tabblad Model.
2. Voeg een taak toe, selecteer het type als Custom en voer een relevante naam in.
3. Selecteer het custom integratiescript en de versie. Als een versie van het script als nieuwste is ingesteld, wordt die versie met nieuwste --> vóór de versienaam weergegeven.
4. Als u een custom bericht in Slack wilt weergeven, voert u de tekst van het bericht in.
  Alle tekst die u invoert, overschrijft de defaultValue in uw custom integratiescript.
Sla uw pijplijn op en schakel deze in.
1. Klik op Opslaan.
2. Klik op de pijplijnkaart op Acties > Inschakelen.
Voer uw pijplijn uit.
1. Klik op Uitvoeren.
2. Bekijk de pijplijn-uitvoering.
3. Controleer of de output de verwachte statuscode, responscode, status en gedeclareerde output bevat.
  U heeft statusCode gedefinieerd als een outputproperty. Bijvoorbeeld: een statusCode van 200 kan duiden op een succesvol Slack-bericht en een responseCode van 0 kan aangeven dat het script zonder fouten is geslaagd.
4. Om de output in de uitvoeringslogboeken te bevestigen, klikt u op Uitvoeringen, klikt u op de link naar uw pijplijn, klikt u op de taak en kijkt u naar de gegevens in het logboek. Bijvoorbeeld:
Als er een fout optreedt, lost u het probleem op en voert u de pijplijn opnieuw uit.
Als een bestand of module in de basisimage bijvoorbeeld ontbreekt, moet u een andere basisimage maken die het ontbrekende bestand bevat. Geef vervolgens het Docker-bestand op en push de image via de pijplijn.

resultaten

Gefeliciteerd! U heeft een custom integratiescript gemaakt waarmee Code Stream wordt verbonden met uw Slack-instantie en een bericht wordt geplaatst op een Slack-kanaal.

Volgende stappen

Ga door met het maken van custom integraties om het gebruik van custom taken in uw pijplijnen te ondersteunen, zodat u de mogelijkheden van Code Stream bij de automatisering van uw software-release-levenscyclus kunt uitbreiden.