はじめに
kintoneではkintone REST APIを提供しています。
kintone REST APIを利用すると、kintoneアプリのレコードの操作、フォーム設計情報の取得やスペースの操作ができます。
kintone REST APIは、kintone上から
kintone REST APIリクエストを送信する APIを利用して実行できます。
しかし、kintoneと外部システムを連携するときなど、別のクラウドサービスやサーバーなどの外部環境から実行することも想定されます。
この記事では、REST APIを試してみたいときに便利なcurl(カール)を使って、コマンドラインからkintone REST APIを実行する方法を紹介します。
curlとは
curl(カール)は、URLを利用してデータ転送できるコマンドラインツールです。
curlを使うと、コマンド1つで手軽にkintone REST APIを実行できます。
Macでは標準でインストールされており、WindowsでもWindows 10 RS4以降で標準インストールされるようになりました。
curlはコマンドラインツールなので、Windowsの場合はコマンドプロンプト、Macの場合はターミナルなどのコマンドラインシェルから実行できます。
curlの基本書式
curlの基本書式は、以下のとおりです。
|
|
項目 | 説明 |
---|---|
[option] |
curlコマンドのオプションを指定します。 たとえば、 -X オプションを使ってGET/POSTなどのHTTPメソッドの指定や、-H オプションを使ってリクエストヘッダーを付けることができます。 |
[url] |
リクエストを送りたい(呼び出したい)URLを指定します。 |
kintoneアプリのレコード取得
さっそく、
1件のレコードを取得する APIを使って、kintoneアプリのレコードの内容を取得してみましょう。
下準備として、kintoneアプリを作成しレコードを1件以上追加しておいてください。
例では、
kintoneアプリストア
にある「
顧客リスト
」を使っています。
また、「サンプルデータを含める」にチェックを入れてアプリを作成しています。
アプリストアからアプリを追加する方法は「
サンプルアプリを追加する
」を参照してください。
1. アプリIDと レコードIDの確認
まずは、どのアプリのどのレコードの内容を確認するか?を決めましょう。
どのアプリか?は「アプリID」、どのレコードか?は「レコードID」を使って指定するので(後述)、これらを確認してみましょう。
-
Webブラウザーで、「顧客リスト」アプリを開きます。
-
レコードの詳細画面を開きます。
-
表示したページのURLに注目してみましょう。
下図のようなURLが表示されているはずです。
sub-domain
の部分は、ご利用中の .com環境のサブドメイン名です。kintoneでは、
/k/
の後の数字がアプリIDで、record=
の後の数字がレコードIDを表しています。
上図のURLでは、アプリIDが11、レコードIDが1ということがわかります。
2. リクエストURLの確認
curlでリクエストを送るURLを確認しましょう。
1件のレコードを取得する APIのドキュメントによると、レコードを取得するためのURLは、https://(サブドメイン名).cybozu.com/k/v1/record.json
です。
リクエストパラメーターには、app
とid
があります。
これは「どのアプリ(=app
)のどのレコード(=id
)の内容を取得するか?」を指定するものです。
1件のレコードを取得するAPIでは、どちらも必須となっているので必ず指定する必要があります。
今回は、パラメーターをHTTPのクエリ文字列として送信する方法で、app
とid
を指定してみましょう。
HTTPクエリ文字列は、以下のルールにしたがって指定します。
- ベースとなるURL(今回は「https://(サブドメイン名).cybozu.com/k/v1/record.json」)の後に
?
をつけます。 - 「
パラメーター名=値
」の形式でリクエストパラメーターを記述します。
リクエストパラメーターが複数ある場合は&
で区切ります。
そのため、レコードの内容を取得するには次のURLを使います。
|
|
3. API実行
リクエストURLを準備できたので、さっそくcurlで実行してみましょう。
-
1件のレコードを取得するAPIのHTTPメソッドはGETなので、
-X
オプションでGET
を指定します。
コマンドラインシェルで、次のコマンドを実行してください。
sub-domain
は、ご利用中の .com環境のサブドメインに合わせてください。1
curl -X GET "https://sub-domain.cybozu.com/k/v1/record.json?app=11&id=1"
-
コマンドが間違っていなければ、こんなメッセージが返ってきたはずです。
1
{"code":"CB_AU01","id":"xxxxxxxxxxxxxxxxxxxx","message":"ログインしてください。"}
"id":"xxx..."
は、エラーIDです。
問い合わせに利用するIDのため、毎回違う文字が返ってきます。
message
は「ログインしてください」となっていて、「ユーザの認証ができていない」というエラーを示しています。
Webブラウザーでkintoneを利用するときにはログイン(認証)が必要なように、kintone REST APIを実行するにも認証が必要です。
kintoneアカウントを持っていない第三者がkintone REST APIを実行して、kintoneのデータが見えてしまうのはまずいですよね。
また、アプリで権限設定している場合、ユーザーによって見えてほしくないアプリやデータもあります。
なので、認証情報も一緒に送信して、誰がkintone REST APIを実行したか?がわかるようにしなければなりません。
では、認証情報を付与して再チャレンジしてみましょう。
4. API実行 リターンズ
kintone REST APIの認証には、「パスワード認証」「APIトークン認証」「セッション認証」があります。
それぞれの違いは、
認証を確認してください。
今回は「パスワード認証」を使ってみましょう。
パスワード認証する場合は、X-Cybozu-Authorization
というリクエストヘッダーと kintoneにログインするログイン名とパスワード を使います。
-
まず、kintoneにログインするログイン名とパスワードを
:
(半角コロン)でつなげ、Base64エンコードします。
たとえば、ログイン名が「Administrator」、パスワードが「cybozu」の場合、「Administrator:cybozu」という文字列をBase64エンコードします。
エンコード方法は、 Base64エンコード方法を参考にしてください。 -
X-Cybozu-Authorization
というリクエストヘッダー をつけてcurlを実行してみましょう。
リクエストヘッダーは、-H
オプションで付与できます。
コマンドラインシェルで、次のコマンドを実行してください。
sub-domain
は、ご利用中の .com環境のサブドメインに合わせてください。
BASE64_ENCODED_STRING
は、1. でBase64エンコードした結果に置き換えてください。1
curl -X GET -H "X-Cybozu-Authorization:BASE64_ENCODED_STRING" "https://sub-domain.cybozu.com/k/v1/record.json?app=11&id=1"
もし、BASIC認証を設定している場合は、さらに
Authorization
ヘッダーを付けてください。
参考: Basic認証1
curl -X GET -H "X-Cybozu-Authorization:BASE64_ENCODED_STRING" -H "Authorization:Basic BASE64_ENCODED_STRING" "https://sub-domain.cybozu.com/k/v1/record.json?app=11&id=1"
-
今度こそレコードの内容が返ってきましたね。
1
{"record":{"備考":{"type":"MULTI_LINE_TEXT","value":""},"レコード番号":{"type":"RECORD_NUMBER","value":"1"},"更新者":{"type":"MODIFIER","value":{"code":"cybozu","name":"サイボウズ"}},"作成者":{"type":"CREATOR","value":{"code":"cybozu","name":"サイボウズ"}},"郵便番号":{"type":"SINGLE_LINE_TEXT","value":"3200001"},"会社ロゴ":{"type":"FILE","value":[]},"$revision":{"type":"__REVISION__","value":"1"},"部署名":{"type":"SINGLE_LINE_TEXT","value":"開発本部"},"担当者名":{"type":"SINGLE_LINE_TEXT","value":"川崎 丈史"},"メールアドレス":{"type":"SINGLE_LINE_TEXT","value":"kawasaki_takeshi@example.com"},"更新日時":{"type":"UPDATED_TIME","value":"2019-02-04T00:47:00Z"},"顧客ランク":{"type":"DROP_DOWN","value":"A"},"住所":{"type":"SINGLE_LINE_TEXT","value":"栃木県宇都宮市××××"},"TEL":{"type":"SINGLE_LINE_TEXT","value":"092-××××-××××"},"FAX":{"type":"SINGLE_LINE_TEXT","value":"050-××××-××××"},"作成日時":{"type":"CREATED_TIME","value":"2019-02-04T00:47:00Z"},"会社名":{"type":"SINGLE_LINE_TEXT","value":"戸田ネットソリューションズ"},"$id":{"type":"__ID__","value":"1"}}}
Base64エンコード方法
Windowsの場合
-
メモ帳を開いて、以下の内容のテキストファイルを保存します。
LOGIN_NAME
はログイン名、PASSWORD
はパスワードに置き換えてください。
保存先は「デスクトップ」、ファイル名は「src.txt」とします。1
LOGIN_NAME:PASSWORD
-
コマンドプロンプトで、以下のコマンドを実行します。
デスクトップに「dist.txt」という名前のファイルが作成されます。1 2
cd %USERPROFILE%\Desktop certutil -f -encode ./src.txt ./dist.txt
-
dst.txtを開くと、
-----BEGIN CERTIFICATE-----
と-----END CERTIFICATE-----
の間に、エンコード結果が出力されています。(次の例だと、QWR... から始まる文字列です)
この値をメモしておいてください。
src.txtとdst.txtには、ログインIDとパスワードが記載されています。(Base64エンコードされた文字列は、デコードすることで元の文字列に復元できます)
共用のパソコンを利用している場合などは特に、ゴミ箱に移動してファイルを完全削除してください。
以下は、ログイン名がAdministrator、パスワードがcybozuの場合の結果です。1 2 3
-----BEGIN CERTIFICATE----- QWRtaW5pc3RyYXRvcjpjeWJvenU= -----END CERTIFICATE-----
Macの場合
-
ターミナルで、以下のコマンドを実行します。
LOGIN_NAME
はログイン名、PASSWORD
はそのパスワードに置き換えてください。1
printf 'LOGIN_NAME:PASSWORD' | base64
-
Base64エンコード結果が表示されます。
この値をメモしておいてください。
以下は、ログイン名がAdministrator、パスワードがcybozuの場合の結果です。1 2 3 4
printf 'Administrator:cybozu' | base64 # 実行結果 QWRtaW5pc3RyYXRvcjpjeWJvenU=
5. レスポンス結果の確認
kintone REST APIでは、リクエスト結果をJSON形式で返します。
kintoneでのレコード詳細画面で確認できる内容と見比べてみてください。
|
|
今回はレコード情報を取得したので、最初の要素(プロパティ名)はrecord
となっています。
その後は、レコードに含まれるフィールドの情報が順不同に出力されています。
たとえば、"備考": { "type": "MULTI_LINE_TEXT", "value": "" }
の場合、「備考」というフィールドコードをもつフィールドの種類は、「文字列(複数行)」で、値は空ということがわかります。
フィールド詳細は、
フィールド形式を参照してください。
kintoneアプリのレコード登録
レコードの取得ができたので、今度はレコードを1件登録してみましょう。
1件のレコードを登録するには、
1件のレコードを登録する APIを使います。
レコードを登録するアプリは、 kintoneアプリのレコード取得のときと同じ「 顧客リスト 」を使っています。
1. リクエストURLの確認
リクエストを送るURLを確認しましょう。
1件のレコードを登録する APIのドキュメントによると、レコードを登録するためのURLは、https://(サブドメイン名).cybozu.com/k/v1/record.json
です。
あれ?さっきレコードの取得で使ったURLと同じですね。
REST APIは、操作したい対象(リソース)に対してURLを割り当て、その対象に対してどういう操作をするか? という思想に基づいて設計されています。
「レコードの取得」も「レコードの登録」も操作したい対象は「レコード」なので、同じURLになっています。
ただし、今回は登録する操作をしたいので、データを追加する POST メソッドを利用します。
2. リクエストパラメーターの確認
リクエストパラメーターを確認しましょう。
1件のレコードを登録する APIのドキュメントを見てみると、リクエストパラメーターには、app
とrecord
があります。
これで「どのアプリ(=app
)にどんな内容のレコード(=record
)を登録するか?」を指定しています。
1件のレコードを登録する場合、どちらも必須です。
kintoneアプリのレコード取得(GET)のときはクエリという形でリクエストパラメーターをURLの後にくっつけて指定できました。
POSTの場合、リクエストパラメーターは-d
オプションを使って、登録する値をJSON形式で指定します。
データ構造は
1件のレコードを登録するの「リクエストの例」を参考にしてください。
顧客アプリはたくさんフィールドがあるので、今回は一部抜粋して「顧客名」「部署名」フィールドに値を設定してみましょう。
その場合のリクエストボディの構造は以下のようになります。
|
|
Windowsの場合
Windowsの場合、curlコマンドに日本語(マルチバイト文字)を含めることができません。
リクエストボディをJSON形式のファイルで用意してください。
-
ファイル名の例:body.json
-
文字コード:UTF-8
-
ファイルの内容:
1
{"app": "11", "record": { "会社名": { "value": "サイボウズ株式会社" }, "部署名": { "value": "開発" }}}
3. API実行
リクエストURLと登録するデータがそろったので、APIを実行してみましょう。
今回のポイントは以下の5つです。
-X
オプションでPOST
を指定します。- 認証が必要なので、
-H
オプションで認証情報をヘッダーに追加します。 - 今回はJSON形式でリクエストパラメーターを送るので、
-H
オプションでContent-Type: application/json
を指定します。 -d
オプションで登録したいデータを指定します。- Windowsの場合は、登録したいデータを含むJSONファイルを
@フルパス
で指定します。
- Windowsの場合は、登録したいデータを含むJSONファイルを
- リクエスト先のURLを指定します。
-
コマンドラインシェルで、次のコマンドを実行してください。
sub-domain
はご利用中の .com環境のサブドメインに合わせてください。
BASE64_ENCODED_STRING
は、 kintoneアプリのレコード取得で指定した「ログイン名:パスワード」をBase64エンコードした結果に置き換えてください。Windowsの場合
@C:\Users\User\Desktop\body.json
は、用意したjsonファイルのパスに合わせて書き換えてください。1
curl -X POST -H "X-Cybozu-Authorization:BASE64_ENCODED_STRING" -H "Content-Type: application/json" -d "@C:\Users\User\Desktop\body.json" "https://sub-domain.cybozu.com/k/v1/record.json"
Macの場合
1
curl -X POST -H 'X-Cybozu-Authorization:BASE64_ENCODED_STRING' -H 'Content-Type: application/json' -d '{ "app": "11", "record": { "会社名": { "value": "サイボウズ株式会社" }, "部署名": { "value": "開発" }}}' 'https://sub-domain.cybozu.com/k/v1/record.json'
-
登録に成功すると、こんなメッセージが返ってきます。
1
{"id":"21","revision":"1"}
id
はレコード番号なので、登録されているレコード数によって異なります。
1件のレコードを登録する APIでは、登録したレコードのレコードIDとリビジョン(変更履歴の番号)が返却されます。
おわりに
外部サービスとデータ連携をするには、何かしらの言語でプログラムを実装する必要があります。
その準備段階として、kintone REST APIを試してみたい、アプリやレコードの中身を確認したいときに、curlコマンドでの実行は便利な手段です。
今回は、レコードの取得や登録を紹介しましたが、その他kintone REST APIでできる操作については、 kintone REST APIのドキュメントを参考にしてください。
cybozu developer networkでは、
kintone外部連携Tipsや
いろいろなプログラミング言語でkintone REST APIを実行するためのAPIクライアントも公開しています。
curlコマンドを使いこなしてkintone REST APIの扱いに慣れたら、ぜひkintoneと外部サービスと連携し、もっとkintoneを便利に活用していただければと思います。
このTipsは、2019年2月版kintoneで動作を確認しています。