API を使用したジョブのトリガー

1 month ago • 1 min read

Cloud Server v3.x Server v2.x

CircleCI API を使用してジョブをトリガーする方法について説明します。

⚠️ 注意

このドキュメントでは、従来の CircleCI API 1.0 を使用していますが、このサービスは、 V2 API により、いずれ廃止される予定です。パイプラインのエンドポイントをパイプラインのトリガーとして使用することをご検討ください。

概要
API を使用したジョブの条件付き実行
関連項目

概要

CircleCI API を使用して、.circleci/config.yml で定義したジョブをトリガーします。

curl を使用して deploy_docker ジョブをトリガーする例を以下に示します。

curl -u ${CIRCLE_API_USER_TOKEN}: \
     -d build_parameters[CIRCLE_JOB]=deploy_docker \
     https://circleci.com/api/v1.1/project/<vcs-type>/<org>/<repo>/tree/<branch>

上記の例の代替構文です。

一重引用符を二重引用符に置き換える (-d "build_parameters[CIRCLE_JOB]=deploy_docker")。
角括弧のエスケープ (-d build_parameters\[CIRCLE_JOB\]=deploy_docker)

この例には以下の変数が使用されているためご注意ください。

CIRCLE_API_USER_TOKEN は、パーソナル API トークンです。
<vcs-type>は、選択された VCS (github または bitbucket) を示すプレースホルダー変数です。
<org> は、プレースホルダー変数で、 CircleCIの組織名を指します。
<repo>は、プレースホルダー変数で、レポジトリ名を指します。
<branch>は、プレースホルダー変数で、ブランチ名を指します。

API の関連情報については、CircleCI API ドキュメントをご参照ください。

API を通してジョブをトリガーする場合に考慮すべき重要事項

API によってトリガーされるジョブに workflows セクションが含まれてもかまいません。
ワークフローが、API によってトリガーされるジョブを参照する必要はありません。
API によってトリガーされたジョブは、特定の CircleCI コンテキスト用に作成された環境変数にアクセスできません。
環境変数を使用する場合は、それらの環境変数がプロジェクトレベルで定義されている必要があります。
現在のところ、CircleCI 2.1 とワークフローを使用する場合には、単一のジョブをトリガーすることができません。
CircleCI APIを使って、ワークフローをトリガーすることが可能です。単一のワークフローを再実行することも、パイプラインをトリガーして後続のワークフローを実行することも可能です。

API を使用したジョブの条件付き実行

以下は、デプロイされるビルドに対してのみ setup_remote_docker で Docker イメージをビルドする場合の設定例です。

version: 2
jobs:
  build:
    docker:
      - image: ruby:2.4.0-jessie
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数を参照します。
        environment:
          LANG: C.UTF-8
    working_directory: /my-project
    parallelism: 2
    steps:
      - checkout

      - run: echo "run some tests"

      - deploy:
          name: デプロイ ジョブを条件付きで実行
          command: |
            # これをビルド・デプロイのチェックに置き換えます (すなわち、現在のブランチが "release")
            if [[ true ]]; then
              curl --user ${CIRCLE_API_USER_TOKEN}: \
                --data build_parameters[CIRCLE_JOB]=deploy_docker \
                --data revision=$CIRCLE_SHA1 \
                https://circleci.com/api/v1.1/project/github/$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME/tree/$CIRCLE_BRANCH
            fi

  deploy_docker:
    docker:

      - image: ruby:2.4.0-jessie
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # コンテキスト/プロジェクト UI 環境変数を参照します。
    working_directory: /
    steps:
      - setup_remote_docker
      - run: echo "deploy section running"

この例では以下の点にご留意ください。

必ずビルドジョブの deploy ステップを使用してください。これを使用しないと、並列処理の値が N の場合に、N 回のビルドがトリガーされることがあります。
API 呼び出しを build_parameters[CIRCLE_JOB]=deploy_docker で使用し、deploy_docker ジョブのみが実行されるようにします。

API を使用したジョブのトリガー

概要

API を使用したジョブの条件付き実行

関連項目

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