カテゴリー内の他の記事

kintone REST APIの認証設定について

フォローする

(著者:Cstap 落合 雄一

はじめに

こんにちは。落合@cstapです。

kintone REST APIを外部からリクエストするためは、ユーザー認証のためのヘッダが必要となります。この認証設定について、PHPでフォーム設計情報を取得するサンプルを交えて説明いたします。

kintone REST APIに最低限必要な情報は、サブドメインおよびユーザーのログイン名とパスワードです。また、Basic認証を設定している場合は、Basic認証のログイン名とパスワードも必要となります。また、セキュアアクセスを利用した認証については、別のTipsで紹介したいと思っております。

サブドメイン

サブドメインとは、普段アクセスしている cybozu のURI「https://subdomain.cybozu.com」のsubdomainのことです。このサブドメインは、サイボウズドットコム ストアのドメイン管理で変更することができます。kintone REST APIは、https://subdomain.cybozu.com/k/v1/(コマンド名).jsonというURIで実行します。
ちなみに、ゲストスペース内アプリの場合は、https://subdomain.cybozu.com/k/guest/(スペースのID)/v1/(コマンド名).jsonというURIで実行します。

ユーザー認証

kintone REST APIを実行するリクエストには、ユーザー認証のためのヘッダを追加する必要があります。このヘッダには、普段利用しているログイン名とパスワードを利用します。kintone REST API用に新しいユーザーを作成してもいいかもしれません。

ユーザー認証は、リクエストヘッダに「X-Cybozu-Authorization」を追加し、「ログイン名:パスワード」をBASE64エンコードしたものを値に指定します。PHPで記述すると以下のようになります。

"X-Cybozu-Authorization: " . base64_encode(‘your_login_name:your_password’)

Basic認証

Basic認証は、サイボウズドットコム ストアのセキュリティと認証で設定できます。設定していない場合は、必要ありません。設定している場合は、リクエストヘッダに「Authorization」ヘッダを追加し、「Basic 」と「ログイン名:パスワード」をBASE64エンコードしたものを値に指定する必要があります。PHPで記述すると以下のようになります。

"Authorization:Basic " . base64_encode(‘basic_login_name:basic_password’)

アプリID

アプリIDは、アプリの一覧ページのURLの”k”のあとの部分です。
例えば、「https://subdomain.cybozu.com/k/336/」であれば、”336”となります。

リクエストヘッダ

リクエストヘッダは、kintone REST APIの共通仕様のリクエストヘッダの説明を参考に、Host, Content-Type, X-Cybozu-Authorizationを設定した配列を用意します。Basic認証を利用する場合は、以下を追加してください。

"Authorization:Basic " . base64_encode($basicLoginName . ':' . $basicPassword)

HTTPコンテキスト

PHPのfile_get_contentsを利用してkintone REST APIでリクエストするには、URIとHTTPコンテキストが必要になります。HTTPコンテキストを生成するには、stream_context_createを使います。URIは、”https://your-subdomain.cybozu.com/k/v1/form.json”になります。

サンプル

それでは、上記の情報をもとにkintoneアプリのフォーム設計情報を取得し、結果をダンプ出力してみましょう(^^♪
フォーム設計情報を取得するAPIは、form.jsonです。

ドキュメントにあるレスポンスの例のような結果が得られたのではないでしょうか?

最後に

kintone REST APIでの認証設定についてご理解いただけましたでしょうか?
kintone REST APIの認証には、APIトークンを利用する方法もあります。APIトークンについては、ここを参考にしてください。

今回はサンプルとしてfile_get_contentsを利用しましたが、実際にはライブラリを利用した方が良いでしょう。今後、一般的によく利用されるHTTPクライアントライブラリであるHTTP_Request2やguzzleのTipsも紹介したいと思っております。

 

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

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

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

Avatar
Ryu Yamashita

「HTTPクライアントライブラリ使い比べ」というのも良いですね!一つの言語にも色々方法があって選択に悩む事があります。
結局は最初に見つけたサンプルを使い続けたり、好き好きだったりするのかなぁと思ったりしますが、得失・使いやすさ比べみたいな
お話も頂けると嬉しいです。

ちなみに、自分はcURLを元々コマンドラインでよく使っていたので、PHPでもcurlを使っていました・・・。

Avatar
yanbingms

サンプルありがとうございます。APIトークンを使いたいですが、APIトークン取得用のREST APIは公開されていますか?

//Yanbingms

Avatar
yanbingms

分りました。回答ありがとうございます。APIトークンがプログラムで取得できないと、ユーザー認証のところは手動でトークンを入力するしか方法ないでしょうか?
弊社のKintone連携開発TはC#プログラムでKintone REST APIを使って、Kintoneのユーザー認証、指定アプリからのレコード取得などを試みたが、なかなか上手くいかなかった。お手数ですが、C#版のKintone REST API利用のサンプルコード、Readme注意点をいただけますでしょうか?
また、システム上で何か設定が必要とか教えていただけると助かります。 

Avatar
Ryu Yamashita

設定したトークンのプログラムへの適用方法は要求や作り方によると思いますが、バッチ等であれば、設定ファイルに書いておいて実行時に読み込んだりするのがポピュラーな方法になるのかと思います。

私はC#に明るくないので、コミュニティの過去の投稿をサッと見てみましたが、次の2つが参考になりそうでした。

https://cybozudev.zendesk.com/hc/communities/public/questions/201143740/
https://cybozudev.zendesk.com/hc/communities/public/questions/201220204/

また、3rd party SDK ( https://cybozudev.zendesk.com/hc/ja/sections/200976634 ) を見ると .NET ( https://github.com/icoxfog417/kintoneDotNET ) がありますので、コード変換等試みてみる等の方法も考えられそうです。

C#でのリクエストが上手くいかないということであれば、他のリクエスト方法と比較しながらやってみるのが有効かと思います。( https://www.joyzo.co.jp/blog/699

Avatar
yanbingms

ご教授ありがとうございます。
他の人がC#で成功したことが見えるので、僕も継続で試してみたいと考えています。
お丁寧に教えてくださって、再び感謝します。

Avatar
TAKA

こちらの記事を参考に、PHPでkintoneのとあるアプリの情報を表示させるプログラムを作成しています。

記事の通りに進め、設計情報を表示させることは出来ました。
また、~/form.jsonを~/records.jsonに変更して、レコード情報を表示させることも出来ました。

しかし、全レコード情報が表示されてしまいます。
レコードIDや作成日時などで条件付けして絞り込む方法が分かりません。
HTTPコンテキストのところに、"query" => などと追記してみましたが、だめでした。

参考になる情報を教えていただけましたら大変助かります。
よろしくお願いいたします。

Avatar
Ryu Yamashita

TAKAさん

> "query" => などと追記
file_get_contentsでやったことはないですが、記述方法としては問題ないかと思います。query周りの実際の記述やエラーメッセージはどのようになってますか。

Avatar
TAKA

早速のお返事ありがとうございます。
file_get_contentsではなく、別の方法だと簡単でしょうか。

記述は
"query" => '(レコードID)%20%3D%20(レコード)'
など複数の方法を試していますが、特にエラーは表示されず、クエリ指定を無視して全レコードが羅列されます。

Avatar
Ryu Yamashita

ちらっと手元で試したところ、こんな感じで通せてます。あと、(URLではなく)ボディにリクエスト内容をのせる際には、queryはURLエンコード不要です。

$context = array(
"http" => array(
"method" => 'GET',
"header" => implode("\r\n", $header),
"content" => json_encode(array("app" => $appId, "query" => '$id="60"'))
)
);

Avatar
TAKA

ありがとうございます。
ご提示いただいた例を参考に、クエリの部分を項目名にしてみたところ、
無事、希望の結果を表示させることが出来ました。
大変助かりました。
今後ともよろしくお願いいたします。

Avatar
h-nozaki

私は先日よりREST APIをPHPの`file_get_contents()`にて取得するプログラムを書いているのですが、上記の例を使用させてもらうと

```

$context = array(
"http" => array(
"method" => 'GET',
"header" => implode("\r\n", $header),
"content" => json_encode(array("app" => $appId, "query" => '$id="60"')),

'ignore_errors' => true,
)
);

```

がないとエラー時にwarningになってエラー内容を取得できませんでした。

私はハマったので一応参考までに。

Avatar
cybozu Development team

h-nozakiさん

こんにちは。cybozu developer network運営事務局です。
コメントが遅くなりすみません。
上記の点お教えくださりありがとうございます。

本文の書き方だとWarningが出たときに、エラー内容まで出力されないので、
その内容まで取得できるようにignore_errorsをTRUEに設定している。
また最終的にはエラーキャッチしてWarningのときもレスポンスボディを取得したいという理解で合ってますでしょうか?
https://havelog.ayumusato.com/develop/php/e188-php_file_get_contents_tips.html

ご確認お願いします。

Avatar
h-nozaki

はい。
合っていると思います。

例えばフィールドコード`id`を指定してレコードの取得をしようとして、仮にフィールドコード`id`がない場合下記のようなエラーが返されると思います。
```
array(
'code' => 'XXXX_XX11',
'id' => '0000000000-0000000',
'message' => '指定されたフィールド(id)が見つかりません。'
)
```

ですが`ignore_errors`を設定していないとPHPの`Warning`になり、API側のエラー内容(レスポンスボディー)が取得出来ない状態になります。
```
Warning Error: file_get_contents(https://example.cybozu.com/k/v1/records.json): failed to open stream: HTTP request failed! HTTP/1.1 520 520
```

Avatar
榎田
榎田により編集されました
Avatar
榎田
榎田により編集されました
ログインしてコメントを残してください。
Powered by Zendesk