Search Results for ""

API リファレンス

CircleCI API を使用すると、ユーザー、ジョブ、ワークフロー、パイプラインに関する詳細情報を取得する API を呼び出すことができます。 現在、以下の 2 つのバージョンの API がサポートされています。

API v2 には、API v1.1 にはない強力な機能が備わっています (パイプラインやパイプライン パラメーターのサポートなど)。できるだけ早くスクリプトを API v2 の安定したエンドポイントに移行することをお勧めします。

正式にサポートされ一般提供されているのは CircleCI API v1.1 と API v2 の一部です。 CircleCI は、安定していることが宣言されている API v2 のエンドポイントが増えてきたため、最終的には API v1.1 のサポートを終了し、完全に API v2 に切り替えたいと考えています。 CircleCI API v1.1 の廃止時期についての詳細は、後日お知らせします。

API v2 の概要

CircleCI API v2 では、API エクスペリエンスを向上させる新しい機能を備えたエンドポイントを使用できるほか、ジョブでの API の使用を最適化することができます。 API v2 は現在も活発に開発が進められているため、API の安定性は「混在」した状態とされています。

現在の API v2 の各エンドポイントは、以下のカテゴリに分けられます。

  • 認証
  • パイプライン
  • ワークフロー
  • ユーザー (プレビュー)
  • プロジェクト (プレビュー)
  • ジョブ (プレビュー)

メモ: CircleCI API v2 の一部は現在もプレビュー中です。 プレビューのエンドポイントは、まだ完全にはサポートされておらず、一般提供のレベルにありません。 API v2 のプレビュー エンドポイントの大きな変更は前もって計画され、API v2 の重大変更ログで発表されます。

API v2 の利用開始

CircleCI API v2 は、リポジトリ名でプロジェクトを識別する方法で、以前のバージョンの API との下位互換性を備えています。 たとえば、CircleCI から GitHub リポジトリ (https://github.com/CircleCI-Public/circleci-cli) についての情報を取得する場合、CircleCI API ではそのリポジトリを gh/CircleCI-Public/circleci-cli と表現します。これは、プロジェクトのタイプ、組織の名前、リポジトリの名前から成り、「トリプレット」と呼ばれます。 プロジェクトのタイプとしては、github または bitbucket、短縮形の gh または bb が使用できます。この短縮形は API v2 でサポートされるようになりました。 組織は、お使いのバージョン管理システムにおけるユーザー名または組織名です。

API v2 では、project_slug というトリプレットの文字列表現が導入されており、このプロジェクト スラッグは次のような形式をとります。

<プロジェクト タイプ>/<組織名>/<リポジトリ名>

project_slug は、プロジェクトに関する情報を取得する際や、ID でパイプラインやワークフローを検索する際に、ペイロードに含めます。 project_slug が、プロジェクトについての情報を得る手段となります。 将来的には、project_slug の形式が変更になる可能性もありますが、いかなる場合でも、プロジェクトの識別子として人が判読できる形式が用いられるはずです。

認証

CircleCI API v2 では、API トークンを HTTP リクエストのユーザー名として送信するだけで、ユーザーの認証が可能です。 たとえば、シェルの環境で CIRCLECI_TOKEN を設定している場合は、以下のように curl コマンドでそのトークンを指定します。

curl -u ${CIRCLECI_TOKEN}: https://circleci.com/api/v2/me

メモ: パスワードがないことを示すために : が記述されています。

パイプライン

CircleCI API v2 では、プロジェクトでパイプラインを有効化する必要があります。 パイプラインを有効化することで、以下のメリットを活用できます。

  • Use the new API endpoint to trigger a pipeline
  • Use pipeline parameters to trigger conditional workflows.
  • Access to version 2.1 config, which provides:
    • Reusable config elements, including executors, commands and jobs.
    • Packaged reusable config, known as orbs.
    • Improved config validation error messages.
    • Option to enable auto-cancel, within Advanced Settings, to abort workflows when new builds are triggered on non-default branches.

Note, it is important to carefully consider the impact of enabling the auto-cancel feature, for example, if you have configured automated deployment jobs on non-default branches.

For more detailed information on pipelines and how you can use their properties in your workflows and jobs, please see the following guides:

パラメーターを使用したパイプラインのトリガーの例

以下は、パラメーターを使用したパイプラインを curl でトリガーする例です。

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

上記の例では、project_slug の形式は :vcs/:org/:project になります。 たとえば、プロジェクト スラッグが gh/CircleCI-Public/circleci-cli とすると、CircleCI に対して、GitHub の組織「CircleCI-Public」のリポジトリ「circleci-cli」にあるプロジェクトを使用するよう指示します。

重要: パイプライン パラメーターは機密データとしては扱われないため、機密の値 (シークレット) には使用しないでください。 機密データの正しい使い方については、プロジェクト設定コンテキストの説明を参照してください。

エンドポイントの変更

CircleCI API v2 リリースで追加されたエンドポイントもあれば、サポートされなくなったエンドポイントもあります。 以降のセクションに、このリリースで追加されたエンドポイントとサポートされなくなったエンドポイントをまとめています。

API v2 のすべてのエンドポイントは、API v2 リファレンス ガイドをご覧ください。このガイドには、各エンドポイントの詳細な説明、必須および任意のパラメーターの情報、HTTP ステータスとエラー コード、ワークフローで使用する場合のコード例が掲載されています。

新しいエンドポイント

最新の v2 バージョンの CircleCI API に追加された新しいエンドポイントは以下の表のとおりです。

エンドポイント 説明
GET /workflow/:id リクエスト内で渡されるパラメーター id に基づいて、個別のワークフローが返されます。
GET /workflow/:id/jobs 固有の id に基づいて、特定のワークフローに関連付けられているジョブをすべて取得します。
GET /project/:project_slug 固有のスラッグに基づいて、特定のプロジェクトを取得します。
POST /project/:project_slug/pipeline 指定したプロジェクトに対して新規パイプラインをトリガーします。
GET /pipeline/:id リクエスト内で渡す id に基づいて、個別のパイプラインを取得します。
GET /pipeline/:id/config 特定のパイプラインの設定ファイルを取得します。
GET /project/:project_slug/pipelines/[:filter] 特定のプロジェクトの最新のパイプライン セットを取得します。

非推奨エンドポイント

最新の API v2 リリースでサポートされなくなったエンドポイントは以下の表のとおりです。

エンドポイント 説明
POST /project/:vcs-type/:username/:project 新規ビルドをトリガーします。
POST /project/:vcs-type/:username/:project/build 指定したプロジェクトで新規ビルドをトリガーします。
DELETE /project/:vcs-type/:username/:project/build-cache 特定のプロジェクトのプロジェクト キャッシュをクリアします。
GET /recent-builds 最近のビルドのサマリーを配列で取得します。

オンプレミス版をご利用のお客様

API v2 は現在、CircleCI Server のセルフホスティング環境ではサポートされていません。