Skip to content
Docs
Cancel

CircleCI Runner API

Last updated
Tags Cloud Server v3.x

認証方法

CircleCI ランナー API は、さまざまな認証方法に対応しています。 使用できる認証方法は、エンドポイントや用途によって異なります。 1 つのエンドポイントで複数の認証方法を使用できる場合もあります。

Circle-Token (個人認証)

この認証方法はパーソナル トークンをベースにしており、CircleCI v2 API と同じルールが適用されます。

名前 説明

circle-token ヘッダー

ユーザー認証に使用される circle-token が含まれたヘッダー

ユーザー名による HTTP Basic 認証

トークンは、Basic 認証のスキームを使用して提供できます。 ユーザー名には circle-token を設定し、パスワードは空白のまま残します。

ブラウザー セッション認証

リクエストに含まれる Cookie を使用して開始する Ring セッションです。 この認証方法では、ユーザーが既に circleci.com にログインしている場合に、特定のエンドポイントにシームレスにアクセスできます。

ローンチ トークン

このトークンは、launch-agent のセットアップに使用するものと同じです。

サポートされている方法

名前 説明

HTTP Bearer 認証

Bearer スキームを使用してトークンを送信します。

エンドポイント

GET /api/v2/runner

指定したパラメーターに基づいて利用可能なランナーの一覧を取得できます。 フィルター用パラメーターを 1つ以上使用することが必須です。

認証方法

  • Circle-Token (個人認証)

  • ブラウザー セッション認証

    • This allows the endpoint to be accessible on circleci.com/api/v2/runner for users that have already logged into circleci.com.

  • ローンチ トークン

リクエスト
名前 型 入力 必須 説明

resource-class

string

クエリ

省略可

指定したリソース クラスでランナーの一覧を絞り込みます。

namespace

string

クエリ

省略可

指定した名前空間でランナーの一覧を絞り込みます。

サンプル

curl -X GET https://runner.circleci.com/api/v2/runner?resource-class=test-namespace/test-resource \
    -H 'Circle-Token: secret-token'
curl -X GET https://runner.circleci.com/api/v2/runner?namespace=test-namespace \
    -H 'Circle-Token: secret-token'

応答

ステータス 説明 形式

200

エージェントの一覧

JSON

応答スキーム

名前 タイプ 必須 説明

items

オブジェクト配列

true

ランナーの配列

resource_class

string

true

ランナーのリソース クラス

hostname

string

true

ランナーのホスト名

name

string

true

ランナー名

first_connected

文字列 (日付と時刻)

true

ランナーが最初に接続した日時

last_connected

文字列 (日付と時刻)

true

ランナーが最後に接続した日時

last_used

文字列 (日付と時刻)

true

ジョブの実行にランナーを最後に使用した日時

version

string

true

実行中のローンチ エージェントのバージョン

例

{
    "items": [
        {
            "resource_class": "test-namespace/test-resource",
            "hostname": "bobby",
            "name": "bobby-sue",
            "first_connected": "2020-05-15T00:00:00Z",
            "last_connected": "2020-05-16T00:00:00Z",
            "last_used": "2020-05-17T00:00:00Z",
            "version": "5.4.3.2.1"
        }
    ]
}

GET /api/v2/runner/tasks

指定したリソース クラスで未処理のタスクの数を取得します。

認証方法

  • circle-token (個人認証)

  • ブラウザー セッション認証

    • This allows the endpoint to be accessible on circleci.com/api/v2/runner for users that have already logged into circleci.com.

  • ローンチ トークン

リクエスト

名前 タイプ 入力 必須 説明

resource-class

string

クエリ

true

指定したリソース クラスでタスクを絞り込みます。

サンプル

curl -X GET https://runner.circleci.com/api/v2/runner/tasks?resource-class=test-namespace/test-resource \
    -H 'Circle-Token: secret-token'

応答

ステータス 説明 形式

200

未処理のタスクの数

JSON

応答スキーム

名前 タイプ 必須 説明

unclaimed_task_count

整数

true

未処理のタスクの数

例

{
    "unclaimed_task_count": 42
}

GET /api/v2/runner/tasks/running

Get the number of running tasks for a given resource class.

認証方法

  • circle-token (個人認証)

  • ブラウザー セッション認証

    • This allows the endpoint to be accessible on circleci.com/api/v2/runner for users that have already logged into circleci.com.

リクエスト

名前 タイプ 入力 必須 説明

resource-class

string

クエリ

true

指定したリソース クラスでタスクを絞り込みます。

サンプル

curl -X GET https://runner.circleci.com/api/v2/runner/tasks/running?resource-class=test-namespace/test-resource \
    -H 'Circle-Token: secret-token'

応答

ステータス 説明 形式

200

実行中のタスクの数

JSON

応答スキーム

名前 タイプ 必須 お問い合わせ内容

running_runner_tasks

整数

true

実行中のタスクの数

例

{
    "running_runner_tasks": 42
}

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

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

クリエイティブ・コモンズ・ライセンス
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.