API

ScrewdriverのAPIとデータモデルはSwaggerを使ってドキュメント化されています。ドキュメントが古くなることを防ぐため、自動生成され、人が読みやすいインタフェースになっています。

現在のAPIはVersion 4で、全てのAPIは/v4で始まります。

APIのドキュメントは次のURLで確認できます: api.screwdriver.cd/v4/documentation

各自のScrewdriver.cdインスタンスでは、<API URL>/v4/documentationにアクセスしてください。

APIを使用する

Swagger経由で使用する

Swaggerのドキュメントは例とお試しのための編集可能なパラメータを含んでいます。/v4/documentationにアクセスし、APIを呼び出すためのTry it out!ボタンをお試しください。

Swaggerページ: Swagger page

レスポンス: Swagger response

より詳細なドキュメントは、Modelのリンクをクリックしてください。

Swaggerモデル: Swagger model

Bearer Tokenの取得

Screwdriver UIにログインした後、https://api.screwdriver.cd/v4/auth/tokenまたはあなたの<API URL>/v4/auth/tokenにアクセスしてBearer Tokenを取得します。
次に、API documentationまたはあなたの <API URL>/v4/documentation に戻り、🔒アイコンをクリックして、以下のようにBearer Tokenを入力します。

RESTクライアント経由で実行する

PostmanのようなRESTクライアントをAPIリクエストに使用します。その際、認証トークンが必要です。認証トークンを取得するためには、/v4/auth/loginからログインし、リダイレクト先の/v4/auth/tokenからトークンをコピーしてください。詳しくは認証と認可をご覧ください。

APIリクエストの際のヘッダは以下のようになります。

Content-Type: application/json
Authorization: Bearer <YOUR_TOKEN_HERE>

リクエストの例: Postman response

ユーザまたはパイプライントークンを利用して実行する

APIを利用した簡単なスクリプトのためには、トークンを利用することを推奨します。

トークンを使用して認証する

新しく作成したトークンで認証するには、https://${API_URL}/v4/auth/token?api_token=${YOUR_TOKEN_VALUE}へGETリクエストを送ります。するとtokenのフィールドを持ったJSONオブジェクトが返ってきます。tokenフィールドの値がJSON Web Tokenになっていて、ScrewdriverのAPIへリクエストを送る際にこのJSON Web TokenをAuthorizationヘッダーに付けて使用します。このJWTは12時間の有効期限があるので、期限が切れた後には再度認証を行う必要があります。

例：パイプラインをスタートさせる

以下に、パイプランをスタートさせるためにAPIトークンを使用するやり方をPythonで記述した例があります。この例では直接APIを呼び出しています。

# トークンを使用して認証
auth_request = get('https://api.screwdriver.cd/v4/auth/token?api_token=%s' % environ['SD_KEY'])
jwt = auth_request.json()['token']

# ヘッダーをセット
headers = { 'Authorization': 'Bearer %s' % jwt }

# パイプラインのジョブを取得
jobs_request = get('https://api.screwdriver.cd/v4/pipelines/%s/jobs' % pipeline_id, headers=headers)
jobId = jobs_request.json()[0]['id']

# 最初のジョブを開始する
start_request = post('https://api.screwdriver.cd/v4/builds', headers=headers, data=dict(jobId=jobId))

詳しい情報と例についてはAPIドキュメントをご覧ください。

認証と認可

認証のために、JSON Web Tokens (JWT) を使用しています。JWTはAuthorizationヘッダを必要とします。

Oauthを利用してJWTを生成するには、/v4/auth/login にアクセスします。こちらのエンドポイントにアクセスすると、/v4/auth/token に自動でリダイレクトされます。
ScrewdriverのAPIトークンを利用してJWTを生成するには、APIトークンをクエリパラメータのapi_tokenに設定して/v4/auth/tokenへGETリクエストを送信します。

認可はSCMにより行われます。ScrewdriverはSCMトークンで以下を識別します。

レポジトリへのread, write, adminアクセスを識別します。
- read権限でpipelineを見ることができます。
- write権限でjobの開始と停止ができます。
- admin権限でpipelineの作成、編集、削除ができます。
リポジトリのscrewdriver.yamlの読み込み
リポジトリに対するオープン中のpull-requestのリストを取得
ビルドの成功・失敗情報でpull-requestを更新
Screwdriverが変更の通知を受け取れるよう、リポジトリに対しwebhookを追加・削除

より詳しい情報についてはGitHub OAuthのドキュメントをご覧ください。

バッジ

<your_UI_URL>/pipelines/<your_pipelineId>/badgeのURLを利用して、特定のパイプラインに対する現在のビルドステータスを表す画像を取得できます。ジョブのステータスを表す画像は<your_UI_URL>/pipelines/<your_pipelineId>/<jobName>/badgeを利用することで取得できます。

例えば、このMarkdown形式で書かれたコードを利用することで上のようなバッジを表示できます。status-image URLはバッジの画像で、status-url はパイプラインへのリンクです。

[![Pipeline Status][status-image]][status-url] [![Job Status][job-status-image]][status-url]

[status-image]: https://cd.screwdriver.cd/pipelines/1/badge
[job-status-image]: https://cd.screwdriver.cd/pipelines/1/main/badge
[status-url]: https://cd.screwdriver.cd/pipelines/1

設計思想

ScrewdriverのAPIは次の三原則を念頭に設計されました。

CLIやWebUIなど各ツールで一貫したインターフェースとするため、全てのユーザーデータへの操作をAPI経由にすべき
意図がわかりやすく、人間が読みやすくするため、リソースはREST-fulであるべきで、操作は小さく区切るべき
クライアントのコード自動生成を可能にするため、APIにはバージョンがあり自己文書化されているべき

自作する

Swaggerドキュメントを作成したい場合は、次のJSONを参考にしてください: https://api.screwdriver.cd/v4/swagger.json

各自のScrewdriver.cdインスタンスでは、/v4/swagger.json にアクセスしてください。

API