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

目次

はじめに

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の基本書式は、以下のとおりです。

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

kintoneアプリのレコード取得

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

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

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

今回は、パラメーターをHTTPのクエリ文字列として送信する方法で、appidを指定してみましょう。
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

3. API実行

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

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

4. 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=

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

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": "" }の場合、「備考」というフィールドコードをもつフィールドの種類は、「文字列(複数行)」で、値は空ということがわかります。
フィールド詳細は、 フィールド形式を参照してください。

kintoneアプリのレコード登録

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

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

1. リクエストURLの確認

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

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

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

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

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

1件のレコードを登録する APIのドキュメントを見てみると、リクエストパラメーターには、apprecordがあります。
これで「どのアプリ(=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": "開発" }}}

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は、 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を便利に活用していただければと思います。

information

このTipsは、2019年2月版kintoneで動作を確認しています。