@kyanny's blog

Write down what I learnt.

Jenkins のジョブを外部からビルドするには API Token を利用する

Jenkins 1.594 にて確認。

Jenkins の認証ありの場合

「セキュリティを有効化 / Enable security」にチェックを入れている場合。

認証必須環境におけるJenkinsのスクリプトトリガーによるビルドの実行 - そんなこと覚えてない そして Authenticating scripted clients - Jenkins - Jenkins Wiki にあるように、Jenkins のログインユーザー固有の API Token を使って BASIC 認証し、 $JOB_URL/build に POST リクエストを送ればよい。

API Token はユーザー設定ページというものがあり、そこから取得できる。

f:id:a666666:20141219223605p:plain

ログインユーザーのユーザー名が kyanny で API Token が xxxxxxxx だとすると、

$ curl -X POST -u kyanny:xxxxxxxx http://jenkins.example.com/JOB_NAME/build

というリクエストを送ればよい。

(上記は例なので HTTP で POST リクエストを送っているが、 API Token が盗聴される可能性があるので、 HTTPS 接続できるようにしたほうがよい)

Jenkins の認証なしの場合

「セキュリティを有効化 / Enable security」のチェックを外している場合。

ただ単に $JOB_URL/build に POST リクエストを送ればよい。

$ curl -X POST http://jenkins.example.com/JOB_NAME/build
ProTip: "Trigger builds remotely" は設定不要

Enable security をオンにしている場合、ジョブの設定ページの「ビルド・トリガ / Build Triggers」セクションに「リモートからビルド (例: スクリプトから) / Trigger builds remotely (e.g., from scripts)」という項目が表示される(Enable security オフだとこの項目は表示されないらしい

この機能を使ってジョブ固有の認証トークン文字列を設定したらビルド URL へ POST するときに ?token=TOKEN_STRING パラメータが必須...ではなかった。 API Token による BASIC 認証のみでビルドを開始できる。 Trigger builds remotely がオフでも、オンで認証トークンが空文字列でも、任意の文字列を保存しても、いずれの場合も ?token= パラメータを送らずにビルド可能。

$JOB_URL/api/ の Perform a build セクションの最後に、

If security is enabled, the recommended method is to provide the username/password of an account with build permission in the request. Tools such as curl and wget have parameters to specify these credentials. Another alternative (but deprecated) is to configure the 'Trigger builds remotely' section in the job configuration. Then building or polling can be triggered by including a parameter called token in the request.

とあるので、このトークンを使った認証機能のことは忘れてよさそう。Authenticating scripted clients - Jenkins - Jenkins Wiki にある wget を使った例ではいまだに token パラメータ必須のように見えるが、どこかのタイミングで Jenkins の仕様変更があってドキュメントが更新されていないか、単にバグなのかもしれない。

Jenkins で認証の設定をミスって締め出されたときは $JENKINS_HOME/config.xml の useSecurity を false にすればなおる

<useSecurity>false</useSecurity>

に変更して Jenkins を再起動すると Enable security オフの状態に戻るので設定をやり直せばよい。

ちなみに Homebrew でインストールした Jenkins を一般ユーザー権限で起動するとデフォルトの $JENKINS_HOME は $HOME/.jenkins になるので設定ファイルは $HOME/.jenkins/config.xml にある。

Mac OSX の Python 2 にインストールした httpie で一部の SSL URL にアクセスすると "sslv3 alert handshake failure" エラーが出る

httpie が内部で使っている requests という HTTP ライブラリのリポジトリに該当する issue があった。

https GET request fails with "handshake failure" · Issue #2022 · kennethreitz/requests · GitHub

Mac OSX にプリインストールされている OpenSSL が原因とのこと。

提示されている解決方法は、

  1. Homebrew で OpenSSL をインストールし、その後 Homebrew で Python 2 をインストールする(Homebrew でインストールされた OpenSSL とリンクするので以後は問題が発生しなくなる)
  2. Homebrew で OpenSSL をインストールし、その後 PyOpenSSL を新しい OpenSSL でビルドされるようにインストールする

Python 3 なら問題ないらしいので httpie を Python 3 のほうでインストールして使うことにした。

$ brew install python3
$ sudo pip uninstall httpie
$ pip3 install httpie

Jenkins ジョブの中で $JOB_URL などの環境変数を利用するためには Jenkins のシステム設定で Environment variables を有効にした上で Jenkins URL を入力する必要がある

Manage Jenkins -> Configure System から

Global properties -> Environment variables のチェックを入れること(デフォルトではチェックされていない==無効)有効になってないといくつかの環境変数がジョブから参照できないらしい。参考 [#JENKINS-16225] Add note to env-vars.html so user knows that Environment variables configuration is requried to export JENKINS_URL, JOB_URL, BUILD_URL - Jenkins JIRA

f:id:a666666:20141215231111p:plain

Jenkins URL は同じ Configure System ページの下のほうにある Jenkins Location -> Jenkins URL に入力する(これはデフォルトで入力されていた)

Book: Web API: The Good Parts

内容はよくまとまっていた。確かにそこは悩むよね、という点がいくつもカバーされていて、かつ既存の API をリサーチしたまとめを元にベターな選択肢が述べられていて納得感がある。 API の設計や実装に慣れている人でも、迷ったときのリファレンスとして利用できると思う。薄い本なので全体的に言及が浅い印象があるけど、随所でより深い議論へのポインタがあるのもよい(海外ブログの URL とか)

セキュリティの話題を扱う第6章だけ異彩を放っている感じがした。一読する価値はあるけど、バージョニングの話とかレスポンスデータ構造の話とかと比べるとだいぶ毛色が違っていて、この章の一部だけ妙に収まりが悪く感じた。

校正が杜撰だった。あまりにひどくて読みながら誤変換とかミスっぽい部分をメモしたら21箇所もあった。それ以外にも日本語の文章としてなんか変、みたいなのもあった。今まで読んだ本のなかで最低レベルのミスの多さだったと思う。オライリージャパンに指摘のメールを送ったけど、そんなことをするのもこれが初めてだった。


以下読みながらとった、「ここは大事」と感じたメモ。

  • X-HTTP-Method-Override
  • /users/:id/friends/:id で関係テーブルのIDを指定させるべきではない(内部アーキテクチャを意識させない)
  • OAuth 2.0 Grant Type 勉強になった
  • script 要素は 40x 50x だと処理が止まるのでクライアントで検知できない(要実験)
  • id_str 大きな数 JS で問題になるので文字列でも返す
  • ぴったりくるステータスコードが存在しなかった場合には、200 400 500 といった 00 で終わるステータスコードを付けるようにします。 p95 根拠は? 404 が汎用では?
  • モンゴメリースコットが自分を有能に見せる作戦
  • 400 ってリクエストが不正(構文ミスとか)の場合かなって思ってたけどちがうの?
  • HTTP キャッシュ 期限切れモデルと検証モデル
  • rfc1123
  • etag をデータ全体からではなく最終更新日時からハッシュをとる、という手もあるのか
  • 弱い検証 W/"" 広告の例
  • Vary の例わかりやすい
  • Cache-Control stale-while-revalidate 非同期でオリジンにキャッシュ検証
  • api のテストは content-type もチェックすべき
  • プリフライトリクエストは送らない場合もあり得る
  • プリフライト情報をキャッシュできる
  • セマンティックバージョニングも mojombo なのか
  • Blackout test api を一時的に停止してアクセス不能にしてみるテストのこと
  • マイナスのパラメータもチェックしないと本来減るべきポイント数が増えてしまう

あと、「複数バージョンの API を公開していく場合、古いバージョンの API の公開終了をどのようなタイミングで行うとよいか」という説明の図がわかりやすかった。

f:id:a666666:20141214024256j:plain

Web API: The Good Parts

Web API: The Good Parts