Start Building for Free
CircleCI.comアカデミーブログコミュニティサポート

CircleCI API を使った環境変数の挿入

1 month ago1 min read
クラウド
Server 3.x
Server 4.x
このページの内容

API v2

CircleCI API v2 を使用すると、パイプラインパラメーターから変数を渡すことができます。

パイプラインのトリガー に API v2 エンドポイントを使用すると、特定のパラメーターの値でパイプラインをトリガーすることができます。 これを実行するには、POST 本体の JSON パケット内で parameters キーを渡します。

以下の例では、workingdirimage-tag のパラメーター値を使ってパイプラインをトリガーしています。

curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d '{
  "parameters": {
    "workingdir": "./myspecialdir",
    "image-tag": "4.8.2"
  }
}' https://circleci.com/api/v2/project/:project_slug/pipeline

パイプラインパラメーターの詳細については、 パイプラインの値とパラメーター のページをお読みください。

API v1

build_parameters キーを使って環境変数を挿入すると、実行のたびに異なるターゲットに対して機能テストをビルドできます (別々のホストに対して機能テストが必要なステージング環境へのデプロイステップを使った実行など)。

build_parameters を含めるには、bashcurl を使用する以下の例のように Content-type: application/json を含む JSON 本文を送信します。 お好きな言語で HTTP ライブラリを使用することもできます。

{
  "build_parameters": {
    "param1": "value1",
    "param2": 500
  }
}
`curl` を使用します (`$CIRCLE_TOKEN` は、<<managing-api-tokens#creating-a-personal-api-token,パーソナル API トークン>> です)。
curl \
  --header "Content-Type: application/json" \
  --header "Circle-Token: $CIRCLE_TOKEN" \
  --data '{"build_parameters": {"param1": "value1", "param2": 500}}' \
  --request POST \
  https://circleci.com/api/v1.1/project/github/circleci/mongofinil/tree/master

このビルドは、以下の環境変数を受け取ります。

export param1="value1"
export param2="500"

本文が空の POST API 呼び出しをした場合は、名前付きブランチが新規で実行されます。 詳細については、API v1 のドキュメントの ブランチを使った新しいジョブのトリガー を参照してください。

API v1 でビルドパラメーターを使用する場合のベストプラクティス

ビルドパラメーターは環境変数からなります。そのため、その環境変数名は下記の条件を満たしている必要があります。

  • 変数名に使えるのは ASCII 文字列、数字、アンダースコアのみです

  • 数字から始まる変数は使えません

  • 少なくとも 1 文字以上の変数でなければなりません

環境変数への通常の制約以外は、値自体には制限事項はなく、単純な文字列として扱われます。

ビルドパラメーターは各ジョブのコンテナ内で環境変数としてエクスポートされ、.circleci/config.yml のスクリプトやプログラム、コマンドで使われる場合があります。 挿入された環境変数は、ジョブ内ので実行されるステップの内容を変えるために使われる場合もあります。 挿入された環境変数は .circleci/config.yml で定義された値や、プロジェクトの設定で定義された値を上書きしないため、くれぐれもご注意ください。

ビルドパラメーターが読み込まれる順序は保証され ない ため、1 つのビルドパラメーターを別のビルドパラメーターに挿入することは避けてください。 独立した環境変数の順不同のリストとしてビルドパラメーターを設定することを推奨します。

たとえば、以下のパラメーターを渡すとします。

{
  "build_parameters": {
    "foo": "bar",
    "baz": 5,
    "qux": {"quux": 1},
    "list": ["a", "list", "of", "strings"]
  }
}

ビルド時には下記のような環境変数となります。

export foo="bar"
export baz="5"
export qux="{\"quux\": 1}"
export list="[\"a\", \"list\", \"of\", \"strings\"]"

ドキュメントの改善にご協力ください

このガイドは、CircleCI の他のドキュメントと同様にオープンソースであり、 GitHub でご利用いただけます。 ご協力いただき、ありがとうございます。

サポートが必要ですか

CircleCI のサポートエンジニアによる、サービスに関する問題、請求およびアカウントについての質問への対応、設定の構築に関する問題解決のサポートを行っています。 サポートチケットを送信して、CircleCI のサポートエンジニアにお問い合わせください。日本語でお問い合わせいただけます。

または、 サポートサイト から、サポート記事やコミュニティフォーラム、トレーニングリソースをご覧いただけます。