User API の共通仕様

目次

User API は、ユーザーやグループ、組織、役職などの情報を操作するための API です。
このページでは、User API の共通仕様を説明します。
各 API の仕様の詳細は、それぞれの API のページを確認してください。

リクエスト

HTTP メソッド

API によって異なります。

URL

リソース は、API によって異なります。
詳細は各 API のページを確認してください。

https://sample.cybozu.com/v1/リソース

リクエストヘッダー

送信するリクエストに応じて次のリクエストヘッダーを指定します。
kintone REST API リクエストを送信する API を使って、User API を実行する場合、リクエストヘッダーの指定は不要です。

パラメーター名 必須 説明
Host 必須 sample.cybozu.com:443
Content-Type 条件必須 application/json
リクエストボディの形式が JSON 文字列の場合のみ指定します。
X-Cybozu-Authorization 条件必須 「ログイン名:パスワード」を Base64 エンコードした値
パスワードを使って認証する場合は必須です。
詳細は、 パスワード認証 を参照してください。
Authorization 条件必須 「Basic 」と「"Basic認証のユーザー名:Basic認証のパスワード" を Base64 エンコードした値」を結合した値
Basic 認証を設定している場合、必須です。
詳細は、 Basic 認証を設定している環境 を参照してください。

リクエストボディ

JSON 形式で指定します。文字コードは UTF-8 です。

JSON 文字列でエスケープが必要な文字は、\ でエスケープしてください。

クエリパラメーター

GET メソッドの API では、URL のクエリパラメーターとしてリクエストパラメーターを付与し、リクエストを送信できます。
たとえばリクエストパラメーターの size が「100」の場合、クエリパラメーターは次のように指定します。

1
/v1/users.json?size=100
エスケープ

URL の仕様に従い、クエリパラメーターのキーや値はパーセントエンコーディングします。
以下は、クエリパラメーターの「code=cybozu#」をパーセントエンコーディングした例です。

1
/v1/user/organizations.json?code=cybozu%23
配列型のパラメーターを指定する場合

配列を要素に分解してパーセントエンコーディングします。

リクエストパラメーターの codes に、「cybozu#」と「sato-noboru」を指定する例を示します。

  1. codes=[cybozu#,sato-noboru] という配列を要素に分解します。

    1
    
    /v1/users.json?codes[0]=cybozu#&codes[1]=sato-noboru
  2. クエリパラメーターのキーや値をパーセントエンコーディングします。

    1
    
    /v1/users.json?codes%5B0%5D=cybozu%23&codes%5B1%5D=sato-noboru

レスポンス

HTTP ステータスコード

リクエストに成功した場合、200 番台のステータスコードが返ります。
リクエストに失敗した場合、200 番台以外のステータスコードと、次のプロパティをもつオブジェクトが返ります。

パラメーター名 説明
id 文字列 エラー ID
サポートへの問い合わせの際に利用します。
code 文字列 エラーの種類を表すコード
message 文字列 エラーメッセージ
出力されるメッセージの言語は、API を実行したユーザーの 表示言語の設定 (External link) によって異なります。
エラーの例
1
2
3
4
5
{
  "id": "1505999166-897850006",
  "code": "CB_IJ01",
  "message": "不正なJSON文字列です。",
}

CSV ファイルをインポート/エクスポートする API

CSV ファイルをインポートする手順

CSV ファイルをインポートする API は、非同期 API です。
CSV ファイルを使ってインポートするには、次の手順で行います。

  1. ユーザー情報や組織情報などを CSV 形式のファイルで用意します。
  2. CSV ファイルをアップロードする API を使って、CSV ファイルをアップロードします。
  3. ファイルアップロード API のレスポンスとして、ファイルキーが返されます。
  4. ファイルキーをリクエストパラメーターに指定して、取り込むデータに対応する API を実行します。
    たとえば、ユーザー情報をインポートする場合には、 ユーザー情報をインポートする API を実行します。
  5. 実行した API のレスポンスとして、ジョブ番号が返されます。
  6. ジョブ番号をリクエストパラメーターに指定して、 インポートの結果を確認する API を実行します。
  7. 処理結果 API のレスポンスとして、処理結果が返されます。

処理結果が「処理中」の場合には、 インポートの結果を確認する API を実行し直します。

「*」(アスタリスク)の取り扱い

ファイルアップロード API を使ってアップロードする CSV の値に「*」を指定すると、その項目の値は更新されません。
ただし、 CSV でユーザー情報をインポートする API においては、次の例外があります。

  • ログイン名には、「*」を指定できません。
  • カスタマイズ項目に「*」を指定した場合は、項目の値に「*」という文字列が設定されます。

エクスポート

CSV ファイルをエクスポートする API のレスポンスは、標準出力に出力されます。
レスポンスの内容をファイルに書き込みたい場合には、シェルのリダイレクト機能(>)を使用してください。

JavaScript API を使って User API を実行する場合

kintone では、 kintone REST API リクエストを送信する API を使って User API を実行できます。
ただし、次の API は実行できません。

注意事項

  • URL の長さが 4 KB を超える GET リクエストを送信すると、「X-HTTP-Method-Override」ヘッダーが自動的に付与され、POST リクエストとして送信されます。