外部連携API/はじめかた - アットウィキ(@WIKI)ご利用ガイド【7/31更新】

外部連携APIでできること

外部連携APIを使うと、ブラウザを使わずに、外部アプリなどから次のことができるようになります。

• ページの取得
• ページの新規作成
• ページの更新
• ページの削除 (※将来対応予定)
• ページの検索

v1でできないこと:

• ページ名の変更
• 添付ファイルの操作

使うための条件

このAPIを使うには、次の条件を満たしている必要があります。
また、本機能は中級以上の機能となっており、少なくともOAuthやRESTなどと呼ばれるWebやプログラムに関する技術知識が必要です。ご了承ください。

• 対象wikiの管理者であること
• 管理画面の基本設定に「OAuth アプリ管理」が表示されていること（表示されていない場合は現時点で利用できない）
• ページの削除には `wiki:delete` スコープが必要だが、将来対応予定。

アプリを登録する

管理画面の「基本設定」→「OAuth アプリ管理」を開く。

登録画面で入力する項目:

• アプリ名
• リダイレクト URI（1行に1件、HTTPS必須）
• スコープ（使う権限にチェックする。あとから変更できないので、必要なものは登録時に選ぶ）
• offline_access（リフレッシュトークンを使うならチェックする）

スコープのチェックボックスは既定ですべて未チェック。選べるのは `wiki:read` `wiki:write` `wiki:search` `user:read` の4つで、1つもチェックしないまま作成するとエラーになる。`wiki:delete` はこの画面の選択肢に無い（将来対応予定）。

登録後にスコープを変更する手段は無い。増やしたい・減らしたいときはアプリを作り直す。登録できるアプリは1つのwikiにつき3個までなので、上限に達しているときは不要なアプリを削除してから作る。

このガイドの手順どおりに進めるなら、`user:read` `wiki:read` `wiki:write` `wiki:search` の4つと `offline_access` にチェックを入れておく。

作成すると `client_id` と `client_secret` が発行される。`client_secret` は作成時のこの画面でしか表示されないので、その場で必ず保存すること。再表示はできない。

アクセストークンを取得する

アプリの登録が終わったら、OAuth 2.0 の認可コードフロー（PKCE付き）でアクセストークンを取得する。

1. PKCE の値を作る

ターミナルで次を実行し、`VERIFIER` `CHALLENGE` `STATE` を作る。

VERIFIER=$(openssl rand -base64 96 | tr -d '\n=+/' | cut -c1-64)
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')
STATE=$(openssl rand -hex 16)
echo "VERIFIER=$VERIFIER"
echo "CHALLENGE=$CHALLENGE"
echo "STATE=$STATE"

2. ブラウザで認可画面を開く

`CID` をアプリ登録で得た `client_id`、`REDIRECT` を登録したリダイレクト URI に置き換えて、次のURLをブラウザで開く。`redirect_uri` の値はURLエンコードして貼る（`https://example.com/callback` なら `https%3A%2F%2Fexample.com%2Fcallback`）。

https://auth.atwiki.jp/oauth2/auth?response_type=code&client_id=${CID}&redirect_uri=${REDIRECT}&scope=user:read%20wiki:read%20wiki:write%20wiki:search%20offline_access&audience=https://w.atwiki.jp/_api/v1&code_challenge=${CHALLENGE}&code_challenge_method=S256&state=${STATE}

`audience=https://w.atwiki.jp/_api/v1` は必須。これが無いと、取得したトークンはこのAPIで使えない。`scope` に `offline_access` を入れないとリフレッシュトークンが返らない。`state` は戻ってきた値が自分の送った値と一致するか、必ず確認する。

`scope` には、アプリ登録でチェックしたものだけを書く。登録していないスコープをここに書いても、その権限はトークンに載らない。上の例は検索（GET /search）まで使う前提で `wiki:search` を含めている。使わない権限は外してよい（必要なものだけ要求するのが安全）。ページの削除を試したい場合は `wiki:delete` が必要だが、登録画面で選べないため、このページの手順では扱わない。

3. 同意する

ログインした状態で開くと同意画面が表示され、要求したscopeが日本語で並ぶ。内容を確認して承認すると、リダイレクト URI に `code` が付いて戻ってくる。`code` の有効期限は10分なので、届いたらすぐ次の手順に進む。

4. トークンと交換する

戻ってきたURLは `?code=...&scope=...&state=...` の形になっている。コピーするのは `code=` の直後から次の `&` の直前まで。`&scope=...` 以降まで一緒にコピーすると、原因の分かりにくい交換失敗になる。コピーした値を `CODE=<コピーした値>` としてシェル変数に入れる。

`CODE` を使って、アクセストークンと交換する。`CID` `CSECRET` `REDIRECT` は自分の値に置き換える。

curl -s -u "${CID}:${CSECRET}" \
  -d grant_type=authorization_code \
  -d code="${CODE}" \
  --data-urlencode redirect_uri="${REDIRECT}" \
  -d code_verifier="${VERIFIER}" \
  --max-time 15 \
  "https://auth.atwiki.jp/oauth2/token"

成功すると次の形のJSONが返る（値はイメージ）。

{
  "access_token": "<アクセストークン>",
  "refresh_token": "<リフレッシュトークン>",
  "expires_in": 3600,
  "scope": "user:read wiki:read wiki:write wiki:search offline_access",
  "token_type": "bearer"
}

APIを呼ぶときに使うのは `access_token` 、トークンを取り直すときに使うのは `refresh_token` 。`expires_in` はアクセストークンが何秒後に切れるかを表す。

最初のリクエストを送る

トークンが取れたら、疎通確認用の `whoami` を叩いてみる。`ACCESS` は取得したアクセストークン、`WIKIID` は自分のwikiのIDに置き換える。

curl -s -H "Authorization: Bearer ${ACCESS}" \
  --max-time 15 \
  "https://w.atwiki.jp/_api/v1/wikis/${WIKIID}/whoami"

返ってくるJSONの例（値は環境によって変わる。以下はイメージ）:

{
  "subject": "yourwiki:1001",
  "client_id": "3f29a1c2-4b5d-4e6f-8a9b-0c1d2e3f4a5b",
  "wikiid": "yourwiki",
  "scopes": ["user:read", "wiki:read", "wiki:write", "wiki:search"],
  "grant_generation": 1
}

`scopes` には、そのアクセストークンに載っているscopeが並ぶ（`offline_access` が含まれることもある）。ここに必要なscopeが無い場合は、アプリ登録でチェックし忘れているか、認可URLの `scope` に書き忘れている。どちらもトークンを取り直すだけでは直らないので、登録内容から確認する。

トークンの有効期限と更新

アクセストークンの有効期限は1時間、リフレッシュトークンの有効期限は30日。

アクセストークンが切れたら、リフレッシュトークンでトークンを取り直す。`CID` `CSECRET` は自分の値に、`REFRESH` は手元にあるリフレッシュトークンに置き換える。

curl -s -u "${CID}:${CSECRET}" \
  -d grant_type=refresh_token \
  -d refresh_token="${REFRESH}" \
  --max-time 15 \
  "https://auth.atwiki.jp/oauth2/token"

更新のたびにリフレッシュトークンの値も変わるので、新しく返ってきた値を保存し直すこと。古い値はその時点で使えなくなる。

30日間一度もリフレッシュを使わないと、リフレッシュトークンは失効する。その場合は「アクセストークンを取得する」の手順を最初からやり直す。

次に読むページ

• APIリファレンス
• エラーと制限