(著者:サイボウズ kintone開発チーム 小林 大輔)
「APIトークン」とは
kintone の APIトークンとは、アプリごとに「トークン」と呼ばれる文字列を発行し、
この文字列をREST APIのリクエストヘッダに付けることで、REST APIを実行することができる、というものです。
従来のREST APIの実行方法に比べて、APIトークンを使ったREST APIの実行方法は様々なメリットがあります。
メリット1:ユーザIDとパスワードが必要ない
従来のREST APIの実行方法では、ユーザIDとパスワードをREST APIを実行するシステムに保存しておく必要がありました。
これではパスワードを変更することが難しくなりますし、REST APIを実行するシステムからユーザ情報が漏洩するリスクも発生してしまいます。
APIトークンでREST APIを実行する際にはユーザIDとパスワードは必要ないので、よりセキュアになります。
メリット2:限られたアプリにのみ、REST APIを実行できる
APIトークンは、アプリごとに作成され、作成されたアプリに対してのみREST APIを実行できます。
これによって、誤ったアプリを操作してしまうといった誤動作を防ぐことができます。
メリット3:実行できるREST APIの種類を制限することができる
APIトークンは、実行できるREST APIの種類を制限することができます。
例えば「アプリのレコード取得APIを実行できるが、レコード更新APIは実行できない」といった設定が可能です。
これによって意図しないAPIを実行してしまうといった問題を防ぐことができます。
また、万が一APIトークンが漏洩してしまった場合に、不正操作のリスクを最小限に抑えることができます。
APIトークンの作成
今回は、APIトークンを実際に作成し、レコード一括取得APIを実行してみましょう。
APIトークンを作成するには、アプリ管理画面を開きます。
アプリ管理画面の中にある「設定」タブをクリックし、表示された「カスタマイズ/サービス連携」メニューにある「APIトークン」をクリックしましょう。
以下のような画面が表示されます。
「生成する」ボタンを押すと、APIトークンが1つ生成され、「アクセス権」の欄にいくつかのチェックボックスが表示されます。
このチェックボックスを使って、作成したAPIトークンが実行できるAPIの種類を決めることができます。
デフォルトでは「レコード閲覧」にチェックが入っており、レコードの取得APIのみ実行できるトークンになります。
今回はこの設定のまま「保存」ボタンを押し、「設定完了」ボタンを押してアプリを更新しましょう。
APIトークンでREST APIを実行する
作成したAPIトークンを使ってみましょう。以下のようにcurlコマンドでREST APIを実行します。
curl -H "X-Cybozu-API-Token: {作成したAPIトークン}" "https://{ドメイン名}/k/v1/records.json?app=(アプリID)"
コマンドを実行すると、アプリに登録されているレコードが表示されます!
(※Basic認証を設定している場合は別途オプションが必要です。こちらのページの「-u オプション」をご参照ください)
また、複数の API トークンを指定すると、ルックアップフィールドを含むアプリのレコード登録や更新、関連レコードの取得ができます。
詳しくは「複数 API トークンを使ってできること」をご参照ください。
ご覧頂いたように、APIトークンを使うことで、ユーザIDやパスワードを使う必要がなくなり、よりセキュアにREST APIを実行することができます。是非使ってみて下さい!
※APIトークンはREST APIを実行するためのトークンであるため、JavaScript API内では利用できないので注意してください。
このTipsは、2014年6月版で確認したものになります。
試用版を利用しているところ、REST APIの呼び出しが失敗しました。
試用版でREST APIの利用が可能でしょうか。
curl -H "X-Cybozu-API-Token: (作成したAPIトークン)" "https://(サブドメイン名).cybozu.com/k/v1/record.json?app=9&id=1"
で試しましたが、、認証が通らないようです。
HTTP 520のレスポンスメッセージ
{"message":"ログインしてください。","id":"1505999166-787662019","code":"CB_AU01"}
dylanさん
cybozu.com developer network事務局です。
試用版であっても問題なく使えます。
おそらく権限か、リクエスト内容に誤りがあると思われます。
メソッドを指定していないようですがいかがですか?
記載例に従い、curlコマンドで、APIトークン認証を試したころ、以下の現象が発生しました。
Rest APIの利用方法を調べ始めた初心者のため、基本的質問ですいませんが、環境と実行コマンドは以下の通りなので、原因を教えていただけますでしょうか?
-OS環境: Windows7 Pro SP1 x86版
-実行コマンド
>curl -o c:\temp\log.txt -H "X-Cybozu-API-Token:xxx" "https://xxx.cybozu.com/k/v1/record.json?app=14&id=1" --proxy proxy.xxx.co.jp:8080
-返信結果
ファイル出力結果:{"code":"GAIA_IA02","id":"39UX7blqb9wb3BogaJ1i","message":"指定したAPIトークンは、アプリで生成されたトークンと異なります。アプリのAPIトークンの設定を確認してください。設定が正しい場合、APIトークンの設定がアプリに反映されていない場合があります。アプリの設定を更新し、APIトークンの設定をアプリに反映します。"}
ファイル出力しない場合: 上記メッセージが文字化けして表示される
-確認依頼内容
Q1. 上記エラー原因と、どのようにコマンドを修正すればエラーが回避できるか教えてください
Q2. 返信エラーメッセージの解説はどこを見れば、解説が記載されているか教え手ください。
※ GAIA_IA02で検索しましたが、うまく見つけることができませんでした。
Q3. ファイル出力せず、コンソール出力をするとメッセージが文字化けします。
コンソール出力でも文字化けしない良い方法があれば教えてください。
以上、
念のための補足情報です。
APIトークン番号は、該当アプリからコピペしているので、間違えていない事は何度も確認済みです。
yamada様
> Q1. 上記エラー原因と、どのようにコマンドを修正すればエラーが回避できるか教えてください
指定したAPIトークンは、アプリで生成されたトークンと異なります。アプリのAPIトークンの設定を確認してください。(以下略)は、
認証に使ったAPIトークンが不正な場合に表示されるメッセージです。
考えられる原因は次のとおりです。
- APIトークンのコピー漏れ(最後の1文字が足りないなど)
- APIトークンを生成後、「アプリを更新」ボタンを押し忘れている
>Q2. 返信エラーメッセージの解説はどこを見れば、解説が記載されているか教え手ください。
>※ GAIA_IA02で検索しましたが、うまく見つけることができませんでした。
- 現状APIリクエストのエラーコードやメッセージの仕様は公開されておりません。ご不便をおかけします。
>Q3. ファイル出力せず、コンソール出力をするとメッセージが文字化けします。
>コンソール出力でも文字化けしない良い方法があれば教えてください。
コンソールの表示する文字コードが合っていないようです。
コンソールに使っているツールの文字コード変更方法を調べていただき、UTF-8に変更いただくと解決するかと存じます。
開発チーム様、
素早い回答、ありがとうございました。
Q1は、記載後に他の問い合わせをみていたらふと気がつき、試した結果下記原因で解決できました。
> - APIトークンを生成後、「アプリを更新」ボタンを押し忘れている
Q3はWindows標準のコマンドプロンプトを使っているため、utf8の設定はできないようです。
curlを使ったほうがとりあえずのAPI機能理解は便利なので、適当なツールを探してみます。
以上、
上記内容に一部に間違いがあったため、自己フォローです。
> Q3はWindows標準のコマンドプロンプトを使っているため、utf8の設定はできないようです。
Re: Google検索で調べた結果、Windows標準のコマンドプロンプトでも以下のコマンドを実行すれば、utf8に設定可能でした。
ちなみに、ターミナル表示フォントの設定変更も必要なようです。
>chcp 65001 ← 補足説明:コマンドプロンプトのデフォルトをutf8にする
h.yamada様
問題解決されたのこと、また、コマンドプロンプトで文字コード変更されたとのこと、ご連絡ありがとうございます。
生成されるAPIトークンの最大文字数は何文字でしょうか。
田中 秀和 様
お世話になっております。cybozu developer network 事務局です。
ご質問いただきました API トークンの最大文字数については、
外部仕様として定義していないためお答えすることができません。
よろしくお願いいたします。
返答ありがとうございました。
2019年12月のアップデートで、複数のアプリをまたがる参照(ルックアップ)をしている場合にも使えるようになっているので、このページからも飛ばせるようにURLを貼っておいてほしいです。
複数 API トークンを使ってできること
菅原直樹 様
お世話になっております。cybozu developer network事務局です。
ご要望ありがとうございます。
社内にフィードバックし、検討させていただきます。
今後とも、よろしくお願いいたします。
APIトークンの有効期限はありますでしょうか?
マニュアル等を見る限り、有効期限は無いとみています。
篠塚 徹也 様
お世話になっております。cybozu developer network 事務局です。
API トークンの有効期限はございません。
よろしくお願いいたします。