curl コマンドで kintone REST API を実行してみよう

Index

• はじめに
• curl とは
• kintoneアプリのレコード取得
• kintoneアプリのレコード登録
• おわりに

はじめに

kintone では kintone REST API を提供しています。kintone REST API を利用すると、kintone アプリのレコードの操作、フォーム設計情報の取得やスペースの操作ができます。
kintone REST API は、kintone 上から kintone.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 の基本書式は、以下のとおりです。

項目	説明
[options]	curl コマンドのオプションを指定します。 例えば、-X オプションを使ってGET/POST などの HTTPメソッドの指定や、-H オプションを使ってリクエストヘッダを付けることができます。
[url]	リクエストを送りたい（呼び出したい）URL を指定します。

kintoneアプリのレコード取得

さっそく、レコードの取得（1件） を使って、kintone アプリのレコードの内容を取得してみましょう。

事前準備として、kintone アプリを作成しレコードを1件以上追加しておいてください。

例では、kintone アプリストア にある「顧客リスト」を使っています。また、「サンプルデータを含める」にチェックを入れてアプリを作成しています。
アプリストアからアプリを追加する方法は「アプリストアからアプリを追加する」をご参照ください。

1. アプリID と レコードID の確認

まずは、どのアプリのどのレコードの内容を確認するか？を決めましょう。
どのアプリか？は「アプリID」、どのレコードか？は「レコードID」を使って指定するので（後述）、これらを確認してみましょう。

1. Web ブラウザで、「顧客リスト」アプリを開きます。
2. レコードの詳細画面を開きます。
3. 表示したページの URL に注目してみましょう。下図のような URL が表示されているはずです。
   ※ sub-domain の部分は、ご利用中の .com 環境のサブドメイン名です。
   
   kintone では、/k/ の後の数字がアプリID で、record= の後の数字がレコードID を表しています。
   上図の URLでは、アプリID が 11、レコードIDが 1 ということがわかります。

2. リクエストURLの確認

curl でリクエストを送るURLを確認しましょう。

レコードの取得（1件）  によると、レコードを取得するためのURL（URI）は、https://(サブドメイン名).cybozu.com/k/v1/record.json です。
リクエストパラメータには、app と id があります。これは「どのアプリ(=app)のどのレコード(=id)の内容を取得するか？」を指定するものです。
レコードの取得（1件）では、どちらも必須となっているので必ず指定する必要があります。

今回は、パラメータをHTTPのクエリ文字列で送信する方法で、app と id を指定してみましょう。
HTTPクエリ文字列は、以下のルールに従って指定します。

1. ベースとなるURL（今回は「https://(サブドメイン名).cybozu.com/k/v1/record.json」）の後に ? をつけます。
2. 「パラメータ名=値」の形式でリクエストパラメータを記述します。リクエストパラメータが複数ある場合は & で区切ります。

例では、アプリIDが11、レコードIDが1のレコード内容を取得したいので、下記のようなURLになります。

3. API 実行

リクエスト URL を準備できたので、さっそく curl で実行してみましょう。

1. レコードの取得（1件）の HTTPメソッドは GET なので、 -X オプションで GET を指定します。
   コマンドラインシェルで、下記のコマンドを実行してください。
   sub-domain は、ご利用中の .com 環境のサブドメインに合わせてください。
2. コマンドが間違っていなければ、こんなメッセージが返ってきたはずです。
   ※ "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 にログインするログイン名とパスワードを使います。

1. まず、kintone にログインするログイン名とパスワードを : (半角コロン) でつなげ、Base64エンコードします。
   例えば、ログイン名が「Administrator」、パスワードが「cybozu」の場合、「Administrator:cybozu」という文字列を Base64エンコードします。
   
   Base64エンコード方法がわからない場合は、以下を参考にしてください。
   
   • Windows の場合
     1. メモ帳 を開いて、以下の内容のテキストファイルを保存します。LOGIN_NAME はログイン名、PASSWORD はパスワードに置き換えてください。
        保存先は「デスクトップ」、ファイル名は「src.txt」とします。
     2. コマンドプロンプトで、以下のコマンドを実行します。デスクトップに「dist.txt」という名前のファイルが作成されます。
     3. dst.txt を開くと、-----BEGIN CERTIFICATE----- と -----END CERTIFICATE-----の間に、エンコード結果が出力されています。（下記の例だと、QWR... から始まる文字列です。）
        この値をメモしておいてください。
        ※ src.txt と dst.txt には、ログインIDとパスワードが記載されています。（Base64エンコードされた文字列は、デコードすることで元の文字列に復元できます。）
        共用のパソコンを利用している場合などは特に、ゴミ箱に移動してファイルを完全削除してください。
        以下は、ログイン名が Administrator、パスワードが cybozu の場合の結果です。
        
   • Mac の場合
     1. ターミナルで、以下のコマンドを実行します。LOGIN_NAME はログイン名、PASSWORD はそのパスワードに置き換えてください。
        
     2. Base64エンコード結果が表示されます。この値をメモしておいてください。
        以下は、ログイン名が Administrator、パスワードが cybozu の場合の結果です。
        
2. X-Cybozu-Authorization というリクエストヘッダ をつけて curl を実行してみましょう。リクエストヘッダは、 -H オプション で付与できます。
   コマンドラインシェルで、下記のコマンドを実行してください。
   sub-domain は、ご利用中の .com 環境のサブドメインに合わせてください。
   BASE64_ENCODED_STRING は、1. でBase64エンコードした結果に置き換えてください。 もし、BASIC 認証を設定している場合は、さらに Authorization ヘッダを付けてください（参考：Basic 認証）
3. 今度こそレコードの内容が返ってきましたね。
   

5. レスポンス結果の確認

kintone REST API では、リクエスト結果を JSON 形式で返します。
kintone でのレコード詳細画面で確認できる内容と見比べてみてください。
今回はレコード情報を取得したので、最初の要素（プロパティ名）は「record」となっています。
その後は、レコードに含まれるフィールドの情報が順不同に出力されています。

例えば、「"備考": { "type": "MULTI_LINE_TEXT", "value": "" }」の場合、「備考」というフィールドコードを持つフィールドの種類は、「文字列（複数行）」で、値は空であることがわかります。
（フィールド詳細は、フィールド形式をご参照ください）

kintoneアプリのレコード登録

レコードの取得ができたので、今度はレコードを1件登録してみましょう。1件のレコードを登録するには、レコードの登録（1件） を使います。

レコードを登録するアプリは、レコードの取得 のときと同じ「顧客リスト」を使っています。

1. リクエストURLの確認

リクエストを送るURLを確認しましょう。

レコードの登録（1件）  によると、レコードを登録するためのURL（URI）は、https://(サブドメイン名).cybozu.com/k/v1/record.json です。
あれ？さっきレコードの取得で使った URL と同じですね。

REST API は、操作したい対象（リソース）に対して URL を割り当て、その対象に対してどういう操作をするか？という思想に基づいて設計されています。
「レコードの取得」も「レコードの登録」も操作したい対象は「レコード」なので、同じ URL になっています。
ただし、今回は登録する操作をしたいので、データを追加する POST メソッドを利用します。

2. リクエストパラメータの確認

リクエストパラメータを確認しましょう。

レコードの登録（1件）  を見てみると、リクエストパラメータには、app と record があります。
これで「どのアプリ(=app)にどんな内容のレコード(=record)を登録するか？」を指定しています。レコード登録（1件）の場合、どちらも必須です。

レコードの取得（GET）のときはクエリという形でリクエストパラメータをURLの後にくっつけて指定できました。
POST の場合、リクエストパラメータは -d オプションを使って、登録する値を JSON 形式で指定します。（データ構造は レコードの登録（1件）> リクエストボディの構造 をご参考ください。）

顧客アプリはたくさんフィールドがあるので、今回は一部抜粋して「顧客名」「部署名」フィールドに値を設定してみましょう。
その場合のリクエストボディの構造は以下のようになります。

Windows の場合

Windows の場合、curl コマンドに日本語（マルチバイト文字）を含めることができません。
リクエストボディを JSON 形式のファイルで用意してください。

• ファイル名の例：body.json
• 文字コード：UTF-8
• ファイルの内容：
  

3. API 実行

リクエスト URL と登録するデータが揃ったので、API を実行してみましょう。

今回のポイントは以下の5つです。

• -X オプションで POST を指定します。
• 認証が必要なので、-H オプションで認証情報をヘッダに追加します。
• 今回は JSON 形式でリクエストパラメータを送るので、-H オプションで Content-Typeがapplication/json であることを指定します。
• -d オプションで登録したいデータを指定します。
  • Windows の場合は、登録したいデータを含む JSON ファイルを@フルパスで指定します。
• リクエスト先のURLを指定します。

1. コマンドラインシェルで、下記のコマンドを実行してください。
   sub-domain はご利用中の .com 環境のサブドメインに合わせてください。
   BASE64_ENCODED_STRING は、レコードの取得 で指定した「ログイン名:パスワード」をBase64エンコードした結果に置き換えてください。
   • Windows の場合
     @C:\Users\User\Desktop\body.json は、用意した json ファイルのパスに合わせて書き換えてください。
     
   • Mac の場合
2. 登録に成功すると、こんなメッセージが返ってきます。
   ※ id はレコード番号なので、登録されているレコード数によって異なります。
   レコードの登録（1件） では、登録したレコードのレコードIDとリビジョン（変更履歴の番号）が返却されます。

おわりに

外部サービスとデータ連携をするには、何かしらの言語でプログラムを実装する必要があります。
その準備段階として、kintone REST API を試してみたい、アプリやレコードの中身を確認したいときに、curl コマンドでの実行は便利な手段です。

今回は、レコードの取得や登録を紹介しましたが、その他 kintone REST API で出来る操作については、ドキュメント をご参考ください。

cybozu developer network では、外部サービスとの連携 Tips や さまざまな言語で REST API を実行できる SDK も公開しています。
curl コマンドを使いこなして kintone REST API の扱いに慣れたら、ぜひ kintone と外部サービスと連携し、もっと kintone を便利に活用していただければと思います。

この記事は、2019年2月版 kintoneで確認したものになります。