🐘YESOD ヘルプ/💡機能別/🦊YESOD アカウントコントロール/🤝🏻AC接続先一覧/AC接続先一覧/Box

Box

概要

Boxは、クラウドコンテンツ管理とファイル共有のためのオンラインストレージサービスです。
YESODではBoxと連携して以下の機能を提供します。
  • Boxのアカウントの作成
  • Boxのロール・グループの割当付与・剥奪
  • Boxのアカウント作成時の初期フォルダーの作成
    • 既存のフォルダーの更新・削除機能の提供はなし。
参考：BoxBoxAIを活用したセキュアなコンテンツ管理、ワークフロー、コラボレーション

コネクタ仕様

業務アセットの作成

1. カスタムアプリを作成する（Boxでの作業）

  1. 開発者コンソール > マイPlatformアプリ > Platformアプリの作成
  1. アプリの種類は、カスタムアプリを選択する。
  1. 認証方法は、サーバー認証(クライアント資格情報許可)を選択する。
  1. 作成されたアプリを選択し、構成タブに遷移する。
  1. アプリアクセスレベルをアプリ + Enterpriseアクセスを選択する。
  1. アプリケーションスコープで以下の項目にチェックが入っていることを確認する。
    1. ユーザーを管理する
    2. グループを管理する
    3. Enterpriseのプロパティを管理する
  1. 高度な機能の以下の項目にチェックを入れる
    1. as-userヘッダーを使用してAPIコールを行う
    2. ユーザーアクセストークンを生成する
  1. 承認作業を行う。(管理者のメールアドレスに承認依頼のメールが送信されます。)
💡
設定イメージ
⚠️
2回目以降の設定変更する場合
Boxのカスタムアプリは変更のたびに管理者の承認が必要になります。
最初の承認の場合はメールが送信されますが、再承認の場合はメールが送信されません。そのため、2回目以降は管理コンソールに遷移して承認作業を行う必要があります。
1回目と2回目以降でフローが変わるのでご注意ください。
参考：アクセス制限付きアプリの承認 - Box Developerドキュメント
 
参考：
 

2. 業務アセットの作成（YESODでの作業）

  1. Boxの開発コンソールから「エンタープライズID」「クライアントID」「クライアントシークレット」に入力する
  1. 接続を選択して同期が完了したら成功
💡
Boxでの取得場所
エンタープライズID
クライアントIDとクライアントシークレット

基本設定

  • パスワードの作成は対応していません。
    • 理由：BoxのAPIではユーザーはすべてInviteのみでパスワードを扱えないため
💡
パスワードの設定イメージ
  1. 作成したユーザーのメールアドレスにログインのURLが送信される。
  1. パスワードの作成をしてログインができるようになる。

アカウント管理

アカウントの作成

Box上に同一のログイン（メールアドレス）のアカウントが存在するかどうかに応じて、以下のような挙動になります。
条件挙動
同一のログインのアカウントがBoxに存在しないアカウントを新規作成する
同一のログインの有効なアカウントがBoxに存在するそのアカウントの情報を更新する
同一のログインの無効（非アクティブ）なアカウントがBoxに存在するそのアカウントを有効にして、情報を更新する
💡
初期フォルダー（等。「同期する項目」参照）を設定している場合、上表のいずれの分岐でもアカウント作成タスクの実行のたびにフォルダーの作成・招待が試みられます。フォルダーやコラボレーション権限がすでに存在する場合は、重複して作成されることはありません。

アカウントの削除

Boxではアカウントの完全な削除には対応しておらず、アカウント削除タスクを実行すると、そのアカウントは「無効化（非アクティブ化）」されます。
⚠️
無効化してもBox上のアカウント自体や、そのアカウントが所有しているファイル・フォルダー、グループへの所属は削除されません。ログインができなくなるだけです。アカウントやデータを完全に削除したい場合は、Box管理コンソールで別途手動の対応が必要です。
Box上ですでにアカウントが削除されている場合（コネクタの管理外で手動削除された場合など）、アカウント削除タスクは（削除対象が見つからないため）成功として扱われます。
💡
無効化されたアカウントに対して、アカウント作成タスクが再度実行されると、そのアカウントは自動的に有効化され、属性マッピングの内容で情報が更新されます（上記「アカウントの作成」の3つ目の条件）。退職者の再入社などでアカウントを引き継ぐ場合にご利用いただけます。

割当種別

ロール

  • Boxの管理コンソールのアクセス権を管理します。
  • タイプ：Priority項目
  • 選択可能項目
    • coadmin(共同管理者)：管理者権限を持つユーザー
    • user(管理対象ユーザー)：管理者権限を持たないユーザー

グループ

  • グループを使用することで複数のユーザーに一括でフォルダーのアクセス権限を付与できます。
  • タイプ：Multiple項目
  • 選択可能項目：APIから取得する。

同期する項目

必須項目

項目マッピング項目YESOD項目型説明
loginuser.loginuser.emailStringログイン用メールアドレス ※ 変更不可(管理画面でも変更不可)
nameuser.nameuser.familyNameLocalPreferred + " " + user.givenNameLocalPreferredStringユーザー名

任意項目

マッピング項目入力形式説明BOXキー名
user.languagestringユーザーの言語（ISO 639-1形式）language
user.timezonestringタイムゾーンtimezone
user.space_amountintegerストレージ使用量（バイト）。-1で無制限space_amount
user.job_titlestring役職（最大100文字）job_title
user.phonestring電話番号（最大100文字）phone
user.addressstring住所（最大255文字）address
user.is_sync_enabledbooleanBox Sync使用可否is_sync_enabled
user.is_external_collab_restrictedbooleanユーザーが社外のユーザーとのコラボレーションを許可されているかどうかis_external_collab_restricted
user.is_exempt_from_device_limitsboolean会社のデバイス制限からユーザーを除外するかどうかis_exempt_from_device_limits
user.can_see_managed_usersbooleanユーザーが自身の連絡先リストで会社の他のユーザーを参照できるかどうかcan_see_managed_users
user.is_exempt_from_login_verificationbooleanユーザーが2要素認証を使用する必要があるかどうかis_exempt_from_login_verification
user.email_aliases[0].emailStringの配列メールエイリアス（企業の登録済みドメインのみ） ※ 洗い替えになっているため、指定していないメールエイリアスは削除されます。 ※ nullを指定した場合は、すべてのメールエイリアスが削除されます。email_aliases[]
user.initial_folder_enabledboolean新規フォルダーを作成するかどうかのオプション(未設定の場合はfalse)-
user.initial_folder_pathString親フォルダーのフルパス-
user.initial_folder_nameString新規フォルダーの名称-

検討の結果、対応外とした項目

項目内容
statusアカウント状態（"active", "inactive", "cannot_delete_edit", "cannot_delete_edit_upload"） * ユーザーの有効・無効をactive/inactiveで管理している。 * 同じ設定項目で、ユーザーの権限的な部分も設定できる。
enterprisenullにすると会社メンバーから外れ無料ユーザーになる。
tracking_codes[]トラッキングコード（管理コンソールで事前設定が必要）
is_password_reset_requiredパスワードリセットを義務付けるか(false→trueのみ)
notification_email.email代替の通知用メールアドレス
💡
画面イメージ
アカウント作成直後は、通知メールが非活性でパスワードリセットに関する項目も存在しない。
 
パスワード設定後に通知メールとパスワードリセットについて入力可能になる。

ドキュメントに記載されているが、対応外とした項目

マッピング項目入力形式説明BOXキー名
user.notifyboolean会社メンバーでなくなった後もメール受信可能かnotify
  • notifyはAPIドキュメントに記載がありますが、以下の理由から対応外としています。
    • Boxが提供しているSDKに項目がない。
    • curlでAPIを直接実行しても値の変動がない。
    • 管理画面に対応する項目がない。
 

グループプッシュ

💡
このセクションでは、グループプッシュ機能を使ってYESODのグループをBoxに連携する際の仕様について説明します。グループプッシュの基本的な使い方は グループプッシュ（設定手順） を参照してください。
グループプッシュを使用すると、YESODに登録されているグループ（組織・会社・事業所・プロジェクト・動的グループ）をBoxの「グループ」として作成・更新・削除できます。
💡
グループプッシュで作成・管理できるのはBoxの「グループ」のみです。「ロール」（管理コンソールのアクセス権）はグループプッシュの対象外です。
⚠️
Boxのグループは階層構造を持ちません。そのため、YESOD上のグループの親子関係はBoxには反映されず、グループを移動（親子関係を変更）してもBox側で対応する操作は発生しません。

グループの作成・更新

Boxのグループ名はエンタープライズ（組織）内で一意です。この一意性を利用して、Box上に同一名のグループが存在するかどうかで、以下のような挙動になります。
条件挙動
同一名のグループがBoxに存在しないグループを新規作成する
同一名のグループがBoxに存在する既存のグループの情報を更新する
⚠️
グループ名による突合が使われるのは、グループを新規に連携するときだけです。すでに連携済みのグループは、名前ではなくBox側のグループIDで対象を特定するため、YESOD側でグループ名を変更した場合はBoxの同じグループが更新されます（Box側のグループ名も新しい名前にリネームされます）。

グループの削除

グループプッシュでのグループ削除は、Box上のグループを完全に削除します（アーカイブや無効化ではありません）。
⚠️
削除は元に戻せません。グループ連携条件の変更によって意図せずグループが連携対象から外れると、Box上のグループそのものが削除されます。連携条件を変更する際は影響範囲にご注意ください。
グループを削除すると、そのグループに与えていたフォルダーのコラボレーション権限（下記「フォルダーオプション」を参照）も失われます。グループを再作成しても権限は自動的には復元されません（フォルダーオプションが有効な場合、次回の同期で招待がやり直されます）。なお、フォルダーオプションで作成したフォルダー自体は削除されません。

同期する項目（グループ属性）

参考：グループ - Box Developerドキュメント
必須項目keyデフォルト値型説明
✅グループ名グループ名（）StringBox上のグループ名。エンタープライズ内で一意である必要があります（255文字以内）。
説明-Stringグループの説明（255文字以内）。
メンバー招待を許可する対象-String（管理者のみ）／（管理者とメンバー）／（すべての管理対象ユーザー）のいずれかを指定します。
メンバー一覧を参照できる対象-String指定できる値はと同じです。
⚠️
は必須項目です。属性マッピングが未設定、または評価結果が空文字・空白のみ・nullの場合は、そのグループの処理が失敗します（グループ作成タスクの他のグループの処理は続行されます）。
 
・は指定できる値が決まっており、範囲外の値が評価された場合はBoxへ送信する前にエラーになります。
 
グループ名（255文字）・説明（255文字）の文字数上限はYESOD側では事前にチェックしていません。超過した場合はBox API側のエラーになります。

値がない場合の挙動

属性マッピングを評価した値が存在しない場合（キーを設定していない、または評価結果がnull）の扱いは、作成時と更新時で異なります。
値を指定している値がない（未設定・null）
グループ作成時指定された値を設定するBoxへ送信せず、Box側のデフォルト値になる
グループ更新時指定された値で更新するBoxへ送信せず、Box上の既存値を保持する（変更なし）
⚠️
更新時、値がない項目は「変更なし」として扱われます。null値で既存の値を削除することはできません。値を空にしたい場合は、空文字を設定できる項目（のみ）に限り、属性式に空文字を評価させることで空にできます。そのため、後からマッピングを外した項目もBox上の値はそのまま残ります（デフォルト値には戻りません）。
 
のみ例外で、更新時も値がなければ処理が失敗します（上記「同期する項目」参照）。

フォルダーオプション

グループプッシュのオプション機能として、グループ専用のフォルダーを作成し、そのフォルダーにグループをコラボレーターとして招待できます。デフォルトは無効です。
💡
キーの考え方はアカウント作成時の初期フォルダー（）と同様で、画面の選択肢には表示されないため、以下のキーを「同期する項目」に直接入力して設定してください。ただし、グループ用のフォルダーは作成後も組織名称の変更などに追従してリネームされ続けるため、キー名には付きません。
必須説明keyデフォルト値値域
フォルダーオプションの有効・無効無効boolean（属性式の評価結果が文字列の場合、（大文字小文字問わず）のみ有効として扱います）
有効時のみ必須フォルダーを配置する親パス-先頭のは連続していても無視されます。末尾にを付けたり、値の途中に連続したを含めたりすると空の階層ができてしまい、設定不備として処理が失敗します。
有効時のみ必須フォルダー名-パス区切り文字（）を含められません。
グループがフォルダーに対して持つアクセスレベル / / / / / /
参考：コラボレーションを作成 - Box Developerドキュメント
⚠️
フォルダーIDはYESOD側で保持していません。同期のたびにグループのコラボレーション一覧からフォルダーを探し直すため、以下の点にご注意ください。
 
  • ・の評価結果はグループごとに一意になるよう設定してください。複数のグループで評価結果が同じになると、それらのグループが同じフォルダーに招待され、中身が共有されます。同じ理由で、グループを削除して同じ評価値のグループを作り直した場合も、残っている旧グループのフォルダーがそのまま使われます（フォルダーは削除されないため）。
  • グループに紐づくフォルダー（YESODが作成したもの）が2件以上検出された場合、どのフォルダーに追従すればよいか判断できないため、そのグループの処理は失敗します。連携済みグループを手動で別のフォルダーへ招待すると、この状態になることがあります。
  • フォルダーの移動先・リネーム先に同名のフォルダーがすでに存在する場合、自動的には解決されず処理が失敗します（グループ作成時の同名グループとは異なり、同名フォルダーをそのまま採用することはしません）。復旧するには、Box側で移動先・リネーム先の同名フォルダーを別の名前にするか移動したうえで、再度同期を実行してください。
  • フォルダー自体の削除、およびフォルダー内のファイルや他のコラボレーションの管理は行いません。グループを削除してもフォルダーは残ります。
  • フォルダー名に使えない文字（ 。パス区切り文字のを除く）の除去・置換は行われません。属性式（など）で対応してください。

必要な権限

グループプッシュを利用するには、Boxのカスタムアプリのアプリケーションスコープで「グループを管理する」が有効になっている必要があります。グループの作成・更新・削除に加えて、フォルダーオプションのコラボレーション操作でもこのスコープを使います（フォルダーオプションのために追加で必要な権限はありません）。
⚠️
「グループを管理する」は本ページの「1. カスタムアプリを作成する（Boxでの作業）」で案内している必須スコープですが、グループの割当を利用していない既存のお客様の環境では有効になっていない場合があります。Boxのカスタムアプリはスコープ変更のたびに管理者の承認が必要で、2回目以降は承認依頼メールが送信されないため（管理コンソールから承認する必要があります）、既存のお客様がグループプッシュを新たに使い始める際はご案内にご注意ください。

注意点

本ページの「割当種別」に記載している「グループ」は、Boxの管理コンソールで作成済みのグループをYESODに取り込み、メンバーへの割当として管理するものです。グループプッシュ（YESODのグループをBox側に新規作成・連携する機能）とは別の機能のため、混同しないようご注意ください。

関連記事

🐘YESOD ヘルプ/💡機能別/🦊YESOD アカウントコントロール/🤝🏻AC接続先一覧/AC接続先一覧/Box