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

CircleCI 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>

Alternative syntaxes for the above example:

  • Replace single quotes with double quotes (-d "build_parameters[CIRCLE_JOB]=deploy_docker")
  • Escape the square brackets (-d build_parameters\[CIRCLE_JOB\]=deploy_docker)

Some notes on the variables used in this example:

  • CIRCLE_API_USER_TOKEN is a personal API token.
  • <vcs-type> is a placeholder variable and refers to your chosen VCS (either github or bitbucket).
  • <org> is a placeholder variable and refers to the name of your CircleCI organization.
  • <repo> is a placeholder variable and refers to the name of your repository.
  • <branch> is a placeholder variable and refers to the name of your branch.

For a complete reference of the API, see the CircleCI API Documentation.

Important Considerations When Triggering A Job Via The API

  • API によってトリガーされるジョブに workflows セクションが含まれてもかまいません。
  • ワークフローが、API によってトリガーされるジョブを参照する必要はありません
  • API によってトリガーされたジョブは、特定の CircleCI コンテキスト用に作成された環境変数にアクセスできません
  • 環境変数を使用する場合は、それらの環境変数がプロジェクトレベルで定義されている必要があります。
  • 現在のところ、CircleCI 2.1 とワークフローを使用する場合には、単一のジョブをトリガーすることができません。
  • It is possible to trigger workflows with the CircleCI API: a singular workflow can be re-run, or you may trigger a pipeline which will run its subsequent workflows.

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

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

The next example demonstrates a configuration for building docker images with setup_remote_docker only for builds that should be deployed.

version: 2
jobs:
  build:
    docker:
      - image: ruby:2.4.0-jessie
        auth:
          username: mydockerhub-user
          password: $DOCKERHUB_PASSWORD  # context / project UI env-var reference
        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  # context / project UI env-var reference
    working_directory: /
    steps:
      - setup_remote_docker
      - run: echo "deploy section running"

Notes on the above example:

  • ビルド ジョブの deploy ステップを必ず使用してください。 これを使用しないと、並列処理の値が N の場合に、N 回のビルドがトリガーされることがあります。
  • 以下は、デプロイされるビルドに対してのみ setup_remote_docker で Docker イメージを構築する場合の設定ファイル例です。

関連項目

トリガー



Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.