APIトークンを使ってみよう

フォローする

(著者:サイボウズ kintone開発チーム 小林 大輔)

「APIトークン」とは

2014年6月のアップデートで、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認証を設定している場合は別途オプションが必要ですので、curlのmanをご参照ください。)

ご覧頂いたように、APIトークンを使うことで、ユーザIDやパスワードを使う必要がなくなり、よりセキュアにREST APIを実行することができます。是非使ってみて下さい!

※APIトークンはREST APIを実行するためのトークンであるため、JavaScript API内では利用できないので注意してください。

このTipsは、2014年6月版で確認したものになります。

記事に関するフィードバック

直接的に記事と関連がないご質問はcybozu developer コミュニティをご活用ください。

Avatar
dylan

試用版を利用しているところ、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"}

Avatar
cybozu Development team

dylanさん
cybozu.com developer network事務局です。
試用版であっても問題なく使えます。
おそらく権限か、リクエスト内容に誤りがあると思われます。
メソッドを指定していないようですがいかがですか?

Avatar
h.yamada

記載例に従い、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. ファイル出力せず、コンソール出力をするとメッセージが文字化けします。

コンソール出力でも文字化けしない良い方法があれば教えてください。

以上、

 

Avatar
h.yamada

念のための補足情報です。

APIトークン番号は、該当アプリからコピペしているので、間違えていない事は何度も確認済みです。

Avatar
cybozu Development team

yamada様

> Q1. 上記エラー原因と、どのようにコマンドを修正すればエラーが回避できるか教えてください

指定したAPIトークンは、アプリで生成されたトークンと異なります。アプリのAPIトークンの設定を確認してください。(以下略)は、

認証に使ったAPIトークンが不正な場合に表示されるメッセージです。

考えられる原因は次のとおりです。

- APIトークンのコピー漏れ(最後の1文字が足りないなど)

- APIトークンを生成後、「アプリを更新」ボタンを押し忘れている

>Q2. 返信エラーメッセージの解説はどこを見れば、解説が記載されているか教え手ください。

>※ GAIA_IA02で検索しましたが、うまく見つけることができませんでした。

- 現状APIリクエストのエラーコードやメッセージの仕様は公開されておりません。ご不便をおかけします。

>Q3. ファイル出力せず、コンソール出力をするとメッセージが文字化けします。

>コンソール出力でも文字化けしない良い方法があれば教えてください。

コンソールの表示する文字コードが合っていないようです。

コンソールに使っているツールの文字コード変更方法を調べていただき、UTF-8に変更いただくと解決するかと存じます。

 

Avatar
h.yamada

開発チーム様、

素早い回答、ありがとうございました。

Q1は、記載後に他の問い合わせをみていたらふと気がつき、試した結果下記原因で解決できました。 

> - APIトークンを生成後、「アプリを更新」ボタンを押し忘れている

Q3はWindows標準のコマンドプロンプトを使っているため、utf8の設定はできないようです。

curlを使ったほうがとりあえずのAPI機能理解は便利なので、適当なツールを探してみます。

以上、

 

Avatar
h.yamada

上記内容に一部に間違いがあったため、自己フォローです。

> Q3はWindows標準のコマンドプロンプトを使っているため、utf8の設定はできないようです。

Re: Google検索で調べた結果、Windows標準のコマンドプロンプトでも以下のコマンドを実行すれば、utf8に設定可能でした。
ちなみに、ターミナル表示フォントの設定変更も必要なようです。

>chcp 65001 ← 補足説明:コマンドプロンプトのデフォルトをutf8にする

Avatar
cybozu Development team

h.yamada様

問題解決されたのこと、また、コマンドプロンプトで文字コード変更されたとのこと、ご連絡ありがとうございます。

ログインしてコメントを残してください。
Powered by Zendesk