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. パラメーター名=値」の形式でリクエストパラメーターを記述します。
    リクエストパラメーターが複数ある場合は & で区切ります。

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

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