kintoneではkintone REST APIを提供しています。
kintone REST APIを利用すると、kintoneアプリのレコードの操作、フォーム設計情報の取得やスペースの操作ができます。

kintone REST APIは、kintone上から kintone REST APIリクエストを送信する APIを利用して実行できます。
しかし、kintoneと外部システムを連携するときなど、別のクラウドサービスやサーバーなどの外部環境から実行することも想定されます。

この記事では、REST APIを試してみたいときに便利なcurl（カール）を使って、コマンドラインからkintone REST APIを実行する方法を紹介します。

curl（カール）は、URLを利用してデータ転送できるコマンドラインツールです。
curlを使うと、コマンド1つで手軽にkintone REST APIを実行できます。
Macでは標準でインストールされており、WindowsでもWindows 10 RS4以降で標準インストールされるようになりました。

curlはコマンドラインツールなので、Windowsの場合はコマンドプロンプト、Macの場合はターミナルなどのコマンドラインシェルから実行できます。

curlの基本書式は、以下のとおりです。

1

curl [option] [url]

さっそく、 1件のレコードを取得する APIを使って、kintoneアプリのレコードの内容を取得してみましょう。
下準備として、kintoneアプリを作成しレコードを1件以上追加しておいてください。

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

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

1. Webブラウザーで、「顧客リスト」アプリを開きます。

2. レコードの詳細画面を開きます。

3. 表示したページのURLに注目してみましょう。
   下図のようなURLが表示されているはずです。
   sub-domainの部分は、ご利用中の .com環境のサブドメイン名です。

   

   kintoneでは、/k/の後の数字がアプリIDで、record=の後の数字がレコードIDを表しています。
   上図のURLでは、アプリIDが11、レコードIDが1ということがわかります。

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

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

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

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

そのため、レコードの内容を取得するには次のURLを使います。

1
2

# アプリIDが11でレコードIDが1の場合
https://{sub-domain}.cybozu.com/k/v1/record.json?app=11&id=1

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

1. 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"

2. コマンドが間違っていなければ、こんなメッセージが返ってきたはずです。

   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を実行したか？がわかるようにしなければなりません。

では、認証情報を付与して再チャレンジしてみましょう。

kintone REST APIの認証には、「パスワード認証」「APIトークン認証」「セッション認証」があります。
それぞれの違いは、 認証 を確認してください。

今回は「パスワード認証」を使ってみましょう。
パスワード認証する場合は、X-Cybozu-Authorizationというリクエストヘッダーと kintoneにログインするログイン名とパスワード を使います。

1. まず、kintoneにログインするログイン名とパスワードを:（半角コロン）でつなげ、Base64エンコードします。
   たとえば、ログイン名が「Administrator」、パスワードが「cybozu」の場合、「Administrator:cybozu」という文字列をBase64エンコードします。
   エンコード方法は、 Base64エンコード方法 を参考にしてください。

2. 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"

3. 今度こそレコードの内容が返ってきましたね。

   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の場合

1. メモ帳を開いて、以下の内容のテキストファイルを保存します。
   LOGIN_NAMEはログイン名、PASSWORDはパスワードに置き換えてください。
   保存先は「デスクトップ」、ファイル名は「src.txt」とします。

   1	LOGIN_NAME:PASSWORD

2. コマンドプロンプトで、以下のコマンドを実行します。
   デスクトップに「dist.txt」という名前のファイルが作成されます。

   1 2	cd %USERPROFILE%\Desktop certutil -f -encode ./src.txt ./dist.txt

3. dst.txtを開くと、-----BEGIN CERTIFICATE-----と-----END CERTIFICATE-----の間に、エンコード結果が出力されています。（次の例だと、QWR... から始まる文字列です）
   この値をメモしておいてください。
   src.txtとdst.txtには、ログインIDとパスワードが記載されています。（Base64エンコードされた文字列は、デコードすることで元の文字列に復元できます）
   共用のパソコンを利用している場合などは特に、ゴミ箱に移動してファイルを完全削除してください。
   以下は、ログイン名がAdministrator、パスワードがcybozuの場合の結果です。

   1 2 3

   -----BEGIN CERTIFICATE----- QWRtaW5pc3RyYXRvcjpjeWJvenU= -----END CERTIFICATE-----

Macの場合

1. ターミナルで、以下のコマンドを実行します。
   LOGIN_NAMEはログイン名、PASSWORDはそのパスワードに置き換えてください。

   1	printf 'LOGIN_NAME:PASSWORD' | base64

2. Base64エンコード結果が表示されます。
   この値をメモしておいてください。
   以下は、ログイン名がAdministrator、パスワードがcybozuの場合の結果です。

   1 2 3 4

   printf 'Administrator:cybozu' | base64 # 実行結果 QWRtaW5pc3RyYXRvcjpjeWJvenU=

kintone REST APIでは、リクエスト結果をJSON形式で返します。
kintoneでのレコード詳細画面で確認できる内容と見比べてみてください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
  "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" }
  }
}

今回はレコード情報を取得したので、最初の要素（プロパティ名）はrecordとなっています。
その後は、レコードに含まれるフィールドの情報が順不同に出力されています。

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

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

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

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

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

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

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

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

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

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

1
2
3
4
5
6
7

{
  "app": "11",
  "record": {
    "会社名": { "value": "サイボウズ株式会社" },
    "部署名": { "value": "開発" }
  }
}

Windowsの場合

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

• ファイル名の例：body.json

• 文字コード：UTF-8

• ファイルの内容：

  1	{"app": "11", "record": { "会社名": { "value": "サイボウズ株式会社" }, "部署名": { "value": "開発" }}}

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

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

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

1. コマンドラインシェルで、次のコマンドを実行してください。
   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'

2. 登録に成功すると、こんなメッセージが返ってきます。

   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で動作を確認しています。