如何將自己的建置工具、測試工具和部署工具與 Code Stream 整合

做為 DevOps 管理員或開發人員，您可以建立自訂指令碼來延伸 Code Stream 的功能。

您可以使用指令碼將 Code Stream 與您自己用於建置、測試和部署應用程式的持續整合 (CI) 和持續交付 (CD) 工具及 API 整合。如果您不公開您的 API 應用程式，則自訂指令碼特別有用。

自訂指令碼幾乎可以執行建置工具、測試工具和部署工具與 Code Stream 整合所需的任何動作。例如，指令碼可與管線工作區搭配使用，以支援建置和測試應用程式的持續整合工作以及部署應用程式的持續交付工作。當管線已完成以及發生其他更多情況時，自訂指令碼可以向 Slack 傳送訊息。

Code Stream 管線工作區支援使用 Docker 和 Kubernetes 執行持續整合工作和自訂工作。

如需有關設定工作區的詳細資訊，請參閱設定管線工作區。

您可以使用其中一種支援的語言撰寫自訂指令碼。在指令碼中，您可以包含業務邏輯，並定義輸入與輸出。輸出類型可包含數字、字串、文字和密碼。您可以建立具有不同業務邏輯、輸入和輸出的多個版本的自訂指令碼。

所建立的指令碼位於 Code Stream 執行個體中。可以匯入 YAML 代碼以建立自訂整合，也可以將指令碼匯出為 YAML 檔案以在其他 Code Stream 執行個體中使用。

您可以讓管線在自訂工作中執行已發行的指令碼版本。如果您有多個已發行版本，則可以將其中一個版本設定為最新版本，以便在選取自訂工作時顯示最新 -->。

當管線使用自訂整合時，如果您嘗試刪除自訂整合，則會顯示一則錯誤訊息，指出您無法將其刪除。

刪除自訂整合會移除所有版本的自訂指令碼。如果您的現有管線具有使用任何版本指令碼的自訂工作，該管線將會失敗。若要確保現有管線不會失敗，您可以取代並撤回您不再需要使用的指令碼版本。如果沒有管線使用該版本，您可以將其刪除。

表 1. 撰寫自訂指令碼後執行的操作
您執行的操作...	有關該動作的詳細資訊...
將自訂工作新增到管線。	自訂工作：在與管線中其他 CI 工作相同的容器中執行。包含輸入變數和輸出變數，指令碼會在管線執行自訂工作之前填入這些變數。支援您在指令碼中定義為輸入和輸出的多種資料類型和各種中繼資料類型。
在自訂工作中選取指令碼。	在指令碼中宣告輸入內容和輸出內容。
儲存管線，然後啟用並執行此管線。	管線執行時，自訂工作會呼叫指定的指令碼版本，並執行其中的業務邏輯，這可將建置、測試和部署工具與 Code Stream 整合。
管線執行後，查看執行情況。	確認管線已交付預期結果。

使用呼叫自訂整合版本的自訂工作時，可以將自訂環境變數作為名稱值配對包含在管線工作區索引標籤上。當產生器映像建立用於執行 CI 工作並部署映像的工作區容器時， Code Stream 會將環境變數傳遞至該容器。

例如，當 Code Stream 執行個體需要 Web Proxy 並且您使用 Docker 主機建立用於自訂整合的容器時， Code Stream 會執行管線並將 Web Proxy 設定變數傳遞至該容器。

表 2. 環境變數名稱-值配對範例
名稱	值
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

名稱-值配對將按如下所示顯示在使用者介面中：

Code Stream 將環境變數傳遞至產生器映像所建立的容器。

此範例將建立自訂整合，該整合會將 Code Stream 連線至 Slack 執行個體，並向 Slack 通道發佈訊息。

必要條件

若要撰寫自訂指令碼，請確認您熟悉下列其中一種語言：Python 2、Python 3、Node.js，或下列任何 Shell 語言：Bash、sh 或 zsh。
使用已安裝的 Node.js 或 Python 執行階段產生容器映像。

程序

建立自訂整合。

按一下自訂整合 > 新增，然後輸入相關的名稱。
選取偏好的執行期間環境。
按一下建立。
指令碼會開啟並顯示程式碼，其中包含所需的執行期間環境。例如， runtime: "nodejs"。指令碼必須包含產生器映像使用的執行期間，以便新增到管線中的自訂工作在管線執行時會成功。否則，自訂工作會失敗。

自訂整合 YAML 的主要區域包括執行階段、代碼、輸入內容和輸出內容。此程序說明了各種類型和語法。


自訂整合 YAML 金鑰	說明
runtime	Code Stream 執行代碼的工作執行階段環境，可以是以下不區分大小寫的字串之一： nodejs python2 python3 shell 如果未提供任何內容，則預設值為 shell。
code	做為自訂工作的一部分執行的自訂業務邏輯。
inputProperties	做為自訂工作組態的一部分進行擷取的輸入內容陣列。這些內容通常會在代碼中使用。
outputProperties	可以從自訂工作匯出以散佈到管線的輸出內容陣列。

使用可用的資料類型和中繼資料，在指令碼中宣告輸入內容。

輸入內容會在 YAML 的 code: 區段中做為內容傳遞到指令碼。


自訂工作 YAML 輸入金鑰	說明	必要
`type`	要顯示的輸入類型： `text` `textarea` `number` `checkbox` `password` `select`	是
`name`	自訂工作的輸入的名稱或字串，將插入自訂整合 YAML 程式碼中。為自訂整合定義的每個輸入內容都必須是唯一的。	是
`title`	管線模型畫布上自訂工作的輸入內容的文字字串標籤。如果保留空白，則預設會使用 `name`。	否
`required`	決定使用者在設定自訂工作時是否必須輸入該輸入內容。設定為 true 或 false。設定為 true 時，如果使用者在管線畫布上設定自訂工作時未提供值，則工作狀態會保持為未設定。	否
`placeHolder`	輸入內容項目區域的預設文字 (如果不存在值)。對應至 html 預留位置屬性。僅支援特定的輸入內容類型。	否
`defaultValue`	自訂工作顯示在管線模型頁面上時，用於填入輸入內容項目區域的預設值。	否
`bindable`	確定建立管線畫布上自訂工作的模型時，輸入內容是否接受貨幣符號變數。在標題旁邊新增 $ 指示符號。僅支援特定的輸入內容類型。	否
`labelMessage`	用作使用者的說明工具提示的字串。在輸入標題旁邊新增工具提示圖示 i。	否
`enum`	接受顯示選取輸入內容選項的值陣列。僅支援特定的輸入內容類型。當使用者選取選項並將其儲存用於自訂工作時，inputProperty 的值會與此值對應，並顯示在自訂工作建模中。例如，值 2015。 2015 2016 2017 2018 2019 2020	否
`options`	透過使用 optionKey 和 optionValue 來接受物件陣列。 optionKey。散佈到工作的代碼區段的值。 optionValue。在使用者介面中顯示選項的字串。僅支援特定的輸入內容類型。選項： optionKey：key1。選取並儲存用於自訂工作後，此 inputProperty 的值將與代碼區段中的 key1 對應。 optionValue：'Label for 1'。使用者介面中 key1 的顯示值，不會顯示在自訂工作的任何其他位置。 optionKey：key2 optionValue：'Label for 2' optionKey：key3 optionValue：'Label for 3'	否
`minimum`	接受做為此輸入內容的有效最小值的數字。僅支援數字類型的輸入內容。	否
`maximum`	接受做為此輸入內容的有效最大值的數字。僅支援數字類型的輸入內容。	否

表 3. 自訂指令碼支援的資料類型和中繼資料
支援的資料類型	支援的輸入中繼資料
字串文字清單：顯示為任何類型的清單對應：顯示為 map[string]any 密碼：顯示為密碼文字方塊，在儲存自訂工作時進行加密數字布林值：顯示為文字方塊 URL：與字串相同，需要進行其他驗證複選、選項按鈕	type：字串或文字... Default：預設值 options：清單或選項對應，要與「複選」或「選項按鈕」搭配使用 min：最小值或最小大小 max：最大值或最大大小 title：文字方塊的詳細名稱 placeHolder：使用者介面預留位置 description：將成為工具提示

例如：

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

在指令碼中宣告輸出內容。

指令碼會從指令碼的業務邏輯 code: 區段擷取輸出內容，您可以在該區段宣告輸出的內容。

當管線執行時，您可以輸入工作輸出的回應代碼。例如， 200。

Code Stream 為每個 outputProperty 提供支援的金鑰。


金鑰	說明
類型	目前包含 `label` 的單一值。
name	自訂整合 YAML 的代碼區塊所發出的金鑰。
title	使用者介面中顯示 outputProperty 的標籤。

例如：

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

若要與自訂指令碼的輸入和輸出互動，請使用 context 取得輸入內容或設定輸出內容。

針對輸入內容： (context.getInput("key"))

針對輸出內容： (context.setOutput("key", "value"))

針對 Node.js：

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

針對 Python：

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

針對 Shell：

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

在 code: 區段中，宣告自訂整合的所有業務邏輯。

例如，在 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();

對自訂整合指令碼進行版本控制並發行之前，請下載適用於 Python 或 Node.js 的內容檔案，並測試指令碼中包含的業務邏輯。
1. 將指標置於畫布頂部，然後按一下內容檔案按鈕。例如，如果指令碼類型為 Python，則按一下 CONTEXT.PY。
2. 修改檔案並儲存。
3. 在開發系統上，借助內容檔案執行並測試自訂指令碼。
將某個版本套用至自訂整合指令碼。
1. 按一下版本。
2. 輸入版本資訊。
3. 按一下發行版本，以在自訂工作中選取指令碼。
4. 若要建立版本，請按一下建立。
(選擇性) 可以將自訂整合指令碼的任何已發行版本設定為最新版本，以便該版本在管線畫布上顯示最新 --> 標籤。
1. 將指標置於畫布頂部，然後按一下版本歷程記錄。
2. 若要查看可用動作，請按一下所需版本對應的水平省略符號，然後選取設定為最新版本。
  
  備註：只有已發行版本才會顯示設定為最新版本動作。
3. 若要確認版本選擇，請按一下設定為最新版本。
4. 若要結束版本歷程記錄並返回指令碼編輯器畫布，請按一下返回箭頭。
若要儲存指令碼，請按一下儲存。
若要將指令碼匯出為 YAML 檔案以在其他 Code Stream 執行個體中使用，請在自訂整合卡上按一下動作 > 匯出，然後選取要匯出的版本。
在管線中，設定工作區。
此範例使用 Docker 工作區。
1. 按一下工作區索引標籤。
2. 選取 Docker 主機和產生器映像 URL。
向管線新增自訂工作並設定該工作。
1. 按一下模型索引標籤。
2. 新增工作，為類型選取自訂，然後輸入相關的名稱。
3. 選取您的自訂整合指令碼和版本。如果已將指令碼的某個版本設定為最新版本，則該版本將在版本名稱之前顯示最新 -->。
4. 若要在 Slack 中顯示自訂訊息，請輸入訊息文字。
  您輸入的任何文字會覆寫自訂整合指令碼中的 defaultValue。
儲存並啟用管線。
1. 按一下儲存。
2. 在管線卡上，按一下動作 > 啟用。
執行管線。
1. 按一下執行。
2. 查看管線執行情況。
3. 確認輸出包含預期的狀態碼、回應代碼、狀態以及已宣告的輸出。
  您已將 statusCode 定義為輸出內容。例如， statusCode 為 200 可能表示 Slack 發佈成功，而 responseCode 為 0 可能表示指令碼已成功且未發生錯誤。
4. 若要確認執行記錄中的輸出，請按一下執行及管線連結，然後按一下此工作查看記錄的資料。例如：
如果發生錯誤，請疑難排解問題，然後重新執行管線。
例如，如果您的基礎映像中遺失檔案或模組，您必須建立包含遺失檔案的另一個基礎映像。然後，提供 Docker 檔案，並透過管線推送映像。

結果

恭喜您！您已建立自訂整合指令碼，該指令碼將 Code Stream 連線至 Slack 執行個體，並向 Slack 通道發佈訊息。

下一步

繼續建立自訂整合，以支援在管線中使用自訂工作，以便延伸 Code Stream 在自動執行軟體發佈生命週期中的功能。