ペイロード バインディングと bash パラメータの拡張を置換で使用する

このページでは、ペイロード バインディングの使い方と、ビルドトリガーに関連付けられた置換変数に bash パラメータの拡張を適用する方法について説明します。ビルド構成で置換変数を使用する方法については、変数値の置換をご覧ください。

Cloud Build を使用すると、トリガーのイベント ペイロードの一部を置換変数として保存できます。イベント ペイロードは、トリガーを呼び出すイベントの本文です。ペイロードに関連付けられた変数はバインディングと呼ばれ、push イベントと pull イベントの両方によって呼び出されるビルドで使用できます。バインディングを使用すると、ソースコードに関連付けられた言語や pull リクエストの作成者など、ビルドに関連する追加データにアクセスできます。

また Cloud Build では、bash パラメータの拡張を置換変数の値に適用できます。bash パラメータの拡張では、既存の変数に関連付けられた文字列を操作できます。大文字への変換や部分文字列の置換により、文字列を操作できます。

Google Cloud Console と Cloud Build 構成ファイルでビルドトリガーを定義または更新する場合、ペイロード バインディングを使用して bash パラメータの拡張を適用できます。また、手動ビルドの実行時に bash パラメータの拡張を適用できます。

ペイロード バインディング

トリガーのイベント ペイロードの一部を置換変数値として保存できます。ペイロード バインディングは、push イベントと pull イベントによって呼び出されるビルドの変数値として使用でき、ソースコードが GitHub リポジトリまたは Cloud Source Repositories にある場合、JSON ペイロードにアクセスするために使用できます。GitHub イベント ペイロードの詳細については、Webhook イベント ペイロードをご覧ください。Cloud Source Repositories のイベント ペイロードの詳細については、Cloud Source Repositories の通知をご覧ください。

イベント ペイロードの情報にアクセスするには、イベント ペイロードのルートを表す接頭辞を指定します。接頭辞から始めて、JSONPath 構文を使用して、ペイロードにアクセスし、そこからデータを pull できます。イベントタイプに応じて、次のペイロードの接頭辞を使用できます。

接頭辞 ソース 説明
push GitHub push イベントの JSON ペイロード内のフィールドへのアクセスを可能にする
pull_request GitHub pull リクエス トイベントの JSON ペイロード内のフィールドへのアクセスを可能にする
issue_comment GitHub pull リクエストに関連する問題のコメント イベントの JSON ペイロード内のフィールドへのアクセスを可能にする
csr Cloud Source Repositories push イベントの JSON ペイロード内のフィールドへのアクセスを可能にする

GitHub アプリに関連付けられているイベントについては、組み込み変数の値 is_collaborator と perm_level も使用できます。push および pull イベントのユーザーのステータスは、変数値 push.pusher.name、pull_request.pull_request.user.login、issue_comment.comment.user.login によってチェックされます。次の表は、ソースコードが GitHub にある場合に、これらをトリガーの変数値として含める方法を示しています。

変数の名前 変数の値 変数の説明
_PERM_LEVEL $(perm_level) ユーザーの権限レベルを取得する
_IS_COLLABORATOR $(is_collaborator) ユーザーが共同編集者の場合、true を出力する

変数値 is_collaborator と perm_level は、push イベント、pull リクエスト イベント、コメントによってゲートされる pull リクエスト イベントに使用できます。これらの変数値の前に接頭辞を付ける必要はありません。

ペイロード バインディングを使用した置換の作成

ペイロード バインディングを使用する置換変数を作成するには:

  1. [トリガー] ページを開きます。

  2. ビルドトリガーを作成していない場合は、[トリガーを作成] をクリックします。それ以外の場合は、既存のトリガーを選択します。

  3. [代入変数] で [変数を追加] をクリックします。

  4. 以下の規則に従って、変数の名前を追加します。

    • 置換はアンダースコア（_）で始まり、大文字と数字のみを使用する必要があります（正規表現 [A-Z0-9_]+ に従います）。こうすると、組み込み置換と競合しなくなります。

    • パラメータの数は 100 パラメータに制限されています。パラメータキーの長さは 100 バイトに、パラメータ値の長さは 4,000 バイトに制限されています。

    ユーザー定義の置換を定義して使用する方法の詳細については、ユーザー定義の置換の使用をご覧ください。

  5. サポートされている接頭辞を使用して、変数の値を追加します。

    ソースコードが GitHub にある場合は、ペイロード バインディングを使用して置換変数内でイベント ペイロードの情報を参照できます。push イベントの JSON ペイロードにアクセスするには、接頭辞 push または body を使用します。次の例では、変数値の push 接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。

    変数の名前 変数の値 変数の説明
    _PUSH_NAME $(push.repository.name) push イベントに関連付けられたリポジトリの名前を取得する
    _COMMITS $(push.commits) push された各 commit を表す commit オブジェクトの配列を取得する
    _OWNER $(push.repository.owner.name) リポジトリ オーナーの名前を取得する
    _URL $(push.repository.html_url) GitHub リポジトリの URL を取得する
    _LANGUAGE $(push.repository.language) push に含まれるソースコードの言語を取得する

    push 接頭辞を使用してアクセスできるフィールドのリストについては、PushEvent をご覧ください。

    pull リクエスト イベントの JSON ペイロードにアクセスするには、接頭辞 pull_request または body を使用します。次の例では、変数値の pull_request 接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。

    変数の名前 変数の値 変数の説明
    _PULL_REQUEST_ID $(pull_request.pull_request.id) pull リクエストの ID を取得する
    _PULL_REQUEST_TITLE $(pull_request.pull_request.title) pull リクエストのタイトルを取得する
    _PULL_REQUEST_BODY $(pull_request.pull_request.body) pull リクエストの本文を取得する
    _USERNAME $(pull_request.pull_request.user.login) pull リクエストの送信者のユーザー名を取得する
    _MERGE_TIME $(pull_request.pull_request.merged_at) pull リクエストがマージされた時刻を取得する

    pull_request 接頭辞を使用してアクセスできるフィールドのリストについては、PullRequestEvent をご覧ください。

    commit イベントの JSON ペイロードにアクセスするには、接頭辞 commit を使用します。次の例では、変数値の commit 接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。

    変数の名前 変数の値 変数の説明
    _COMMIT_URL $(commit.url) commit に関連付けられている URL を取得します。
    _COMMIT_USER $(commit.author.login) commit の作成者のユーザー名を取得します。
    _COMMIT_MESSAGE $(commit.commit.message) commit に関連付けられている commit メッセージを取得します。
    _COMMIT_DATE $(commit.commit.committer.date) commit に関連付けられている日付を取得します。
    _COMMIT_ADDITIONS $(commit.files['*'].additions) commit 内のファイルに関連付けられている追加の数を取得します。

    commit 接頭辞を使用してアクセスできるフィールドのリストについては、commit の取得をご覧ください。

    pull リクエストによって呼び出されるトリガーのコメント制御を有効にすると、トリガーを呼び出すイベントは IssueCommentEvent になり、関連付けられた接頭辞は issue_comment になります。次の例では、変数値の issue_comment 接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。

    変数の名前 変数の値 変数の説明
    _PULL_REQUEST_ID $(issue_comment.issue.id) pull リクエストの ID を取得する
    _PULL_REQUEST_TITLE $(issue_comment.issue.title) pull リクエストのタイトルを取得する
    _STATE $(issue_comment.state) pull リクエストの状態（オープン、クローズなど）を取得する
    _LABELS $(issue_comment.issue.labels) pull リクエストに関連付けられたラベルのリストを取得する
    _LABELS_URL $(issue_comment.issue.labels[?(@.description=="Extra attention is needed")].url) 説明に一致するラベルに関連付けられた URL を取得する

    issue_comment 接頭辞を使用してアクセスできるフィールドのリストについては、IssueCommentEvent をご覧ください。

    ソースコードが Cloud Source Repositories にある場合は、ペイロード バインディングを使用して置換変数内でイベント ペイロードの情報を参照できます。push イベントの JSON ペイロードにアクセスするには、接頭辞 csr または body を使用します。次の例では、変数値の csr 接頭辞が、ビルドの JSON ペイロード情報にアクセスするためのエントリポイントとして使用されます。

    変数の名前 変数の値 変数の説明
    _REPO_NAME $(csr.name) リポジトリの名前を取得します
    _REPO_URL $(csr.url) リポジトリの URL を取得します
    _CREATED_REPO $(csr.createRepoEvent) ユーザーがリポジトリを作成したかどうかを示します
    _REF_EVENT_NAME $(csr.refUpdateEvent.refUpdates['*'].refName) 参照の名前（refs/heads/primary-branch など）

    Cloud Source Repositories でアクセスできるその他のフィールドについては、通知データをご覧ください。

bash パラメータの拡張

デフォルト変数とユーザー定義変数に bash パラメータの拡張を適用できます。サポートされている操作には、部分文字列の置換、文字列のスライス、大文字への変換などがあります。たとえば、デフォルト変数の部分文字列を置き換えて、その変数をイメージタグとして使用できます。

置換変数に指定できる bash パラメータの拡張は次のとおりです。

bash の拡張 説明
${var} var に保存されている文字列値を展開します。
${var^} 文字列の最初の文字を大文字にする
${var^^} 文字列内のすべての文字を大文字にする
${var,} 文字列の最初の文字を小文字にする
${var,,} 文字列内のすべての文字を小文字にする
${var:position} 文字列の最初の position 文字を削除する
${var:position:length} position で指定された数値で始まる文字列をスライスし、lengthで指定された数値まで含める
${var/substring/replacement} substring で指定された値の左端のインスタンスを replacement で指定された値に置き換える
${var//substring/replacement} substring で指定された値のすべてのインスタンスを replacement に指定された値に置き換える
${var/#substring/replacement} substring が var の接頭辞の場合にのみ、substring で指定された値の最初のインスタンスを replacement で指定された値に置き換える
${var/%substring/replacement} substring が var の接尾辞の場合にのみ、substring で指定された値の最初のインスタンスを replacement で指定された値に置き換える
${#var} 文字列の長さを取得する
${var:-default} var が定義されている場合を除き、var を default と評価する

次の bash パラメータの拡張に一致するパターンを指定することもできます。

bash の拡張 説明
${var#pattern} 指定された pattern の左端のインスタンス（このインスタンスも含む）まで、文字列の左側から文字を削除する
${var##pattern} 指定された pattern の右端のインスタンス（このインスタンスも含む）まで、文字列の左側から文字を削除する
${var%pattern} 指定された pattern の最初のインスタンス（このインスタンスも含む）まで、文字列の右側から文字を削除する
${var%%pattern} 指定された pattern の左端のインスタンス（このインスタンスも含む）まで文字列の右側から文字を削除する

指定できるパターンには次のものがあります。

パターン 説明
* ゼロ個以上の英数字と一致します
? 任意の 1 個の英数字と一致します
[ccc] ccc 内の任意の 1 文字と一致します（a-z または 0-9 の間の範囲を含む）
[^c] c にない英数字文字に一致します（lo <= c <= hi の範囲を含む）
c 任意の英数字（c）と一致します
\c *、?、\ などの英数字以外の文字を含む任意の文字（c）と一致します

bash パラメータの拡張を適用する

組み込みまたはユーザー定義の置換変数に bash パラメータの拡張を適用するには:

  1. [トリガー] ページを開きます。

  2. ビルドトリガーを作成していない場合は、[トリガーを作成] をクリックします。それ以外の場合は、既存のトリガーを選択します。

  3. [代入変数] で [変数を追加] をクリックします。

  4. 以下の規則に従って、変数の名前を追加します。

    • 置換はアンダースコア（_）で始まり、大文字と数字のみを使用する必要があります（正規表現 [A-Z0-9_]+ に従います）。こうすると、組み込み置換と競合しなくなります。

    • パラメータの数は 100 パラメータに制限されています。パラメータキーの長さは 100 バイトに、パラメータ値の長さは 4,000 バイトに制限されています。

    ユーザー定義の置換を定義して使用する方法の詳細については、ユーザー定義の置換の使用をご覧ください。

  5. 変数の値を追加して、サポートされている bash パラメータの拡張を組み込み置換変数または別のユーザー定義の置換変数に適用します。

    次の例では、組み込み置換変数 $BRANCH_NAME にデフォルト値の Feature_Secret_Project_#v2 が設定されています。次の表は、$BRANCH_NAME に適用できる bash パラメータの拡張の例を示しています。

    変数の名前 bash の拡張 変数の値 説明
    _BRANCH_LOWERCASE ${$BRANCH_NAME,,} feature_secret_project_#v2 文字列内のすべての文字を小文字にする
    _BRANCH_NO_SUFFIX ${_BRANCH_LOWERCASE%_\#v2} feature_secret_project 指定したパターンと一致する文字列の右側にあるすべての文字を削除する
    _BRANCH_NO_PREFIX ${_BRANCH_NO_SUFFIX#*_} secret_project 最初のアンダースコアまでのすべての文字を削除する
    _BRANCH_FOR_IMAGE_NAME ${_BRANCH_NO_PREFIX//_/-} secret-project すべてのアンダースコアをダッシュに置き換える
    _IMAGE_NAME my-app-${_BRANCH_FOR_IMAGE_NAME}-prod my-app-secret-project-prod 上記で定義した _BRANCH_FOR_IMAGE_NAME 変数を使用してイメージの名前を作成する

    _IMAGE_NAME は、上記の表 my-app-secret-project-prod で指定された値としてトリガーで定義されています。この値は、ビルド構成ファイル内の _IMAGE_NAME の定義をすべてオーバーライドします。次の例では、_IMAGE_NAME（my-app-secret-project-prod）に指定された変数値が、ビルドトリガーが呼び出されたときに _IMAGE_NAME（test-image）のデフォルト値を置き換えます。

    YAML

     steps:
 - name: 'gcr.io/cloud-builders/docker'
   args: ['build',
          '-t',
          'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
          '.']
 substitutions:
     _IMAGE_NAME: test-image #default value
 images: [
     'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
 ]
 options:
     dynamicSubstitutions: true

    JSON 

     {
   'steps': [
     {
       'name': 'gcr.io/cloud-builders/docker',
       'args': [
         'build',
         '-t',
         'gcr.io/$PROJECT_ID/${_IMAGE_NAME}',
         '.'
       ]
     }
   ],
   'substitutions': {
     '_IMAGE_NAME': 'test-image' #default value
   },
   'images': [
     'gcr.io/$PROJECT_ID/${_IMAGE_NAME}'
   ],
   "options": {
     "dynamic_substitutions": true
   }
 }

上記の例で dynamicSubstitutions フィールドを true に設定すると、bash パラメータの拡張を解釈できます。トリガーによってビルドが呼び出された場合、dynamicSubstitutions フィールドは常に true に設定され、ビルド構成ファイルで指定する必要はありません。ビルドを手動で呼び出す場合、ビルドの実行時に bash パラメータの拡張が解釈されるようにするには、dynamicSubstitutions フィールドを true に設定する必要があります。

ペイロード バインディングで bash パラメータの拡張を使用する

バインディングを含む変数を参照する新しい変数を作成するか、バインディングを bash パラメータの拡張とともに文字列化することで、ペイロード バインディングに関連付けられた変数に bash パラメータの拡張を適用できます。次の表は、ペイロード バインディングで bash パラメータの拡張をどのように使用できるかの例を示しています。

変数の名前 変数の値 変数の説明
_URL $(push.repository.html_url) リポジトリの URL を取得する
_URL_CAPITAL ${_URL^^} bash パラメータの拡張を使用して URL 内のすべての文字を大文字にする
_APP_NAME my-app-${_URL_CAPITAL} リポジトリの大文字に変換された URL に接頭辞を追加する
APP_NAME_ID my-app-$(push.repository.html_url)-${_PAYLOAD_ID:0:7} リポジトリ URL とペイロード ID の最初の 7 文字を含むアプリケーション名を作成する

次のステップ