カテゴリー内の他の記事

User API の共通仕様

Index

概要

ユーザーやグループ、組織、役職などのインポート/エクスポート機能を持ったAPIです。

プロトコル

HTTPS

インターフェース

JSON

文字コード

UTF-8

エスケープ

「\」を使用します。

認証

認証方式

パスワード認証

リクエストヘッダに「X-Cybozu-Authorization」を追加し、その値として、ログイン名とパスワードをBASE64エンコードしたものを指定します。

// ログイン名が「Administrator」、パスワードが「cybozu」の場合
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=

セッション認証

kintone や Garoon に適用した JavaScript ファイルから User API を実行する場合には、セッションによる認証を利用できます。

XMLHttpRequest  Fetch API で、POST/PUT/DELETE メソッドの API を実行する場合は、それぞれ次のトークンを付与してください。

認証方式の優先順位

優先順位は以下の通りです。

  1. パスワード認証
  2. セッション認証

セキュリティ設定を行った環境での API の利用

IP アドレス制限を設定している場合

IP アドレス制限を設定している場合には、次のいずれかの方法で Garoon REST API を実行します。

  • User API を実行するサーバーの IP アドレスを許可する
    設定方法の詳細は、ヘルプページを参照してください。
  • Basic 認証を設定している場合は、「Authorization」リクエストヘッダを付与する
    詳細は、Basic 認証を参照してください。
  • 有効期限の過ぎていないクライアント証明書を付与する
    詳細は、クライアント証明書を参照してください。

Basic認証

IP アドレス制限に加え、Basic 認証を設定している場合は、リクエストヘッダに「Authorization」ヘッダを追加します。

  • 「Basic 」と「ログイン名:パスワード」をBASE64エンコードしたものを、「Authorization」ヘッダの値に指定します。
    • 「Basic」 と 「ログイン名:パスワード」 の間は、半角空白が必要です。
    • 「Basic」の BASE64エンコードは不要です。
// ログイン名が「Administrator」、パスワードが「cybozu」の場合
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=

クライアント証明書

クライアント証明書は、ユーザーの利用サービスで「セキュアアクセス」を許可することで発行できるようになります。
セキュアアクセスの利用を許可し、クライアント証明書を発行する方法は、セキュアアクセスを設定するを参照してください。

  • リクエストする URLには、.s を付ける必要があります。
    たとえば、URL が https://sample.cybozu.com の場合は、https://sample.s.cybozu.com です。

SAML 認証を設定している場合

SAML認証設定時に、cybozu.comのパスワード認証、セッション認証でUser APIを利用できます。
cybozu.com のログイン時に SAML 認証のみを使うように制限している場合、パスワード認証による User API の実行がcybozu.com共通管理者のみに制限されます。セッション認証の場合、この制限を受けません。

2要素認証を設定している場合

2要素認証を設定した cybozu.com ユーザーアカウントでは、パスワード認証は利用できません。

パスワード認証以外の認証方式で実行するか、2要素認証を無効にした連携用のユーザーを用意してください。

リクエストヘッダ

以下のリクエストヘッダをAPI実行時に指定します。

ヘッダ名 内容
Host (サブドメイン名).cybozu.com:443


cybozuで Basic 認証を利用しているリクエストヘッダ例

POST /v1/csv/user.json HTTP/1.1
Host: example.cybozu.com:443
X-Cybozu-Authorization: QWRtaW5pc3RyYXRvcjpjeWJvenU=
Authorization: Basic QWRtaW5pc3RyYXRvcjpjeWJvenU=
Content-type: application/json

レスポンス

HTTPステータスコードが「200」であれば正常終了、それ以外はエラー終了です。
エラー時には下記情報を含むJSONデータをレスポンスとして受け取ります。

キー
message エラーメッセージが指定されたロケールで表示されます。
id エラーIDです。問い合わせの際に利用します。
code エラーの種類を表すコードです。

例)

{"message":"不正なJSON文字列です。","id":"1505999166-897850006","code":"CB_IJ01"}

レスポンスヘッダを含んだ例

HTTP/1.1 400 Bad Request
Date: Wed, 21 Mar 2012 13:48:31 GMT
Server: Apache
Strict-Transport-Security: max-age=315360000 ; includeSubDomains
X-Content-Type-Options: nosniff
X-Cybozu-Error: CB_IJ01
Content-Type: application/json;charset=UTF-8
Set-Cookie: JSESSIONID=6DDFFAAA58BAB36D2021589F80EE31C3; Path=/; Secure; HttpOnly
Vary: Accept-Encoding,User-Agent
Connection: close
Transfer-Encoding: chunked
     
{"message":"不正なJSON文字列です。","id":"1505999166-897850006","code":"CB_IJ01"}

インポート

CSV

CSVインポートAPIは、非同期型のAPIです。
基本的に以下のような流れで利用します。

(1) ユーザー情報や組織情報などをCSVとして準備する (手動)
(2) CSVをアップロードする (ファイルアップロードAPI)
(3) ファイルキーが返却される (ファイルアップロードAPIのレスポンス)
(4) 実行したいインポート処理に対してファイルキーを送信する(例:ユーザーインポートAPI(CSV)
(5) ジョブ番号が返却される (例:ユーザーインポートAPI(CSV)のレスポンス)
(6) ジョブ番号を送信して (4) の処理が完了したか確認する (結果確認API)
(7) 処理結果が返却される (結果確認APIのレスポンス) ※処理結果が"処理中"であれば (6) を繰り返す。

API実行時に指定するデータは、CSV のアップロードでは CSV ファイル、
ファイルキーを送信するAPIはファイルキーを JSON 形式で生成し、これをリクエストボディとして送信します。

JSON

JSONインポートAPIは、同期型のAPIです。
CSVインポートとは異なり、JSON形式のデータを直接送信することができます。
importjson.png
(1) ユーザー情報などをJSONとして準備する (手動)
(2) JSONインポートAPIを実行する
(3) 処理結果が返却される(例:ユーザーインポートAPI(JSON)のレスポンス)

エクスポート

エクスポートAPIは、同期型のAPIです。
エクスポート結果はCSVファイルまたはJSON形式で出力することができます。

(1) エクスポートAPIを実行する
(2) CSV または JSON が返却される(エクスポートAPIのレスポンス)
例:ユーザーエクスポートAPI(CSV)ユーザーエクスポートAPI(JSON)

その他

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

原則としてアップロードする CSV のフィールド値に「*」を指定した場合、そのフィールド値は更新しないことを表します。
ただし、ユーザー情報の CSV においては下記の2点で異なる挙動となります。

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

kintone JavaScript APIからの実行

User API を kintone JavaScript APIから実行する場合、kintone.api() を利用することができます。

※下記のUser APIでは kintone.api() を利用できません。

kintone.api() を使って URI の長さが 4KB を超える GET リクエストを送信する場合は、
X-HTTP-Method-Override ヘッダーが付与され POST リクエストが送信されます。

記事に関するフィードバック

記事のコメント欄は記事に対するフィードバックをする場となっております。
右の記事フィードバックのためのガイドを参照してコメントしてください。
記事のリンク切れなど、気になる点がある場合も、こちらのフォームからフィードバックいただけますと幸いです。

サインインしてコメントを残してください。