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

CircleCI セルフホストランナー API

3 months ago1 min read
クラウド
Server v4.x
Server v3.x
このページの内容

このドキュメントには、CircleCI のセルフホストランナーAPIのすべての外部向けエンドポイントが含まれています。 このAPIは、メインの CircleCI v2 API とは別に、セルフホストランナージョブの管理および実行に使用されます。 これは、`runner.circleci.com`でホストされています。

認証方法

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

circle-token (個人認証)

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

名前説明

Circle-Token header

Header that contains the <circle-token> used to authenticate the user.

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

The token can be provided using the Basic scheme, where username should be set as the <circle-token> and the password should be left blank.

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

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

リソースクラストークン認証

このトークンは新しいリソースクラスを作成する際に生成されます。 このトークンはリソースクラスの作成時に一度だけ表示され、再度取得することはできません。

サポートされている方法

名前説明

HTTP Bearer 認証

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

エンドポイント

GET /api/v3/runner

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

認証方法

  • circle-token (個人認証)

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

    • この認証方法では、circleci.com に既にログインしているユーザーが circleci.com/api/v2/runner でエンドポイントにアクセスできるようになります。

  • リソースクラストークン (リソースクラス作成時に生成されます)

リクエスト
名前タイプ入力必須説明

resource-class

文字列

クエリ

省略可

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

namespace

文字列

クエリ

省略可

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

例

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

文字列

true

セルフホストランナーのリソースクラス

hostname

文字列

true

セルフホストランナーのホスト名

name

文字列

true

セルフホストランナー名

first_connected

文字列 (日付と時刻)

true

セルフホストランナーが最初に接続した日時

last_connected

文字列 (日付と時刻)

true

セルフホストランナーが最後に接続した日時

last_used

文字列 (日付と時刻)

true

ジョブの実行にセルフホストランナーを最後に使用した日時

version

文字列

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/v3/tasks

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

認証方法

  • circle-token (個人認証)

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

    • この認証方法では、circleci.com に既にログインしているユーザーが circleci.com/api/v2/runner でエンドポイントにアクセスできるようになります。

リクエスト

名前タイプ入力必須説明

resource-class

文字列

クエリ

true

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

例

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

応答

ステータス説明形式

200

未処理のタスクの数

JSON

応答スキーマ

名前タイプ必須説明

unclaimed_task_count

整数

true

未処理のタスクの数

例

{
    "unclaimed_task_count": 42
}

GET /api/v3/tasks/running

指定したリソースクラスで実行中のタスクの数を取得します。

認証方法

  • circle-token (個人認証)

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

    • この認証方法では、circleci.com に既にログインしているユーザーが circleci.com/api/v2/runner でエンドポイントにアクセスできるようになります。

リクエスト

名前タイプ入力必須説明

resource-class

文字列

クエリ

true

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

例

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

応答

ステータス意味形式

200

実行中のタスクの数

JSON

応答スキーマ

名前タイプ必須意味

running_runner_tasks

int

true

実行中のタスクの数

例

{
    "running_runner_tasks": 42
}

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

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

サポートが必要ですか

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

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

Creative Commons License

CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.