本記事は 2023 年 11 月に発表された新しいチームスペースへの更新についての補足説明です。
https://dropbox.tech/developers/api-updates-to-better-support-team-spaces
チームの構成には本記事公開時点で 3 種類があります。
- no team space (2017年にリリースのチームフォルダを利用できる構成)
- team space (2018年にリリースされたチームでひとつのフォルダを共有する構成)
- updated team space (2023年にリリースされた更新されたチームスペース)
Dropbox では現在すべてのお客様の構成を updated team space へ移行のご案内を進めています。本記事では変更の概要ならびに、no team space 構成または team space 構成から updated team space 構成へ移行される際の使用上の変更点および対応方法を説明します。
構成ごとの特徴
3 つの構成には大きく分けて次のような特徴があります。
| no team space | team space | updated team space | |
|---|---|---|---|
| チーム メンバーの個人フォルダとチームフォルダ | 混在 | 分離 | 分離 |
| チームフォルダへのパス |
|
固定 | 固定 |
| チームメンバーのルート ネームスペース | チームメンバーごとに別のルート ネームスペース | チームでひとつのルートネームスペースを共有 | チームメンバーごとに別のルート ネームスペース |
チームスペースへの移行目的は特に規模の大きいチームを利用されている組織からの要望を受け、チームメンバーのコンテンツとチーム管理のコンテンツを分離すること、チームメンバー全員でチームフォルダへ同じパスを利用できるようにすることを実現することです。
2018 年リリースの team space ではこの課題が解消されていましたが、チームでひとつのルートネームスペースを共有する構成であったため権限がなくアクセスができないチームフォルダも全てのメンバーに表示されてしまい煩わしいという課題がありました。
2023 年リリースの updated team space ではチームメンバーごとに別のルートネームスペースを設定することで、権限がある利用できるフォルダだけが表示されるようになりました。これにより組織内でのフォルダ管理がよりわかりやすくなりました。また、no team space に含まれていたチームフォルダの管理機能が統合されたことにより大規模チームでの管理ニーズにも対応しています。
構成の見分け方
まず、利用されているチームが現在どの構成であるかをみわけるにはWeb UIを用いて判別できます。次の二つの方法を組み合わせることで
(1) (管理者ユーザーを含む) チームメンバーいずれかのアカウントでログインし、個人用フォルダが分離されているか確認する
www.dropbox.com から Web バージョンの Dropbox にログインします。自分の名前がついたフォルダにすべて個人用のファイル、フォルダがまとまっていれば分離されている構成です。なければ、no team space と確定できます。
自分の名前がついた、このフォルダのアイコンはひとりの人型アイコンが表示されています。このフォルダを Dropbox ヘルプ記事や Dropbox API ではチームメンバーフォルダと呼んでいます。
分離されている構成では、ファイルやチームフォルダをひとつも共有されていない状態でも、チームメンバー フォルダは必ず追加されていますのでこの有無で見分けることができます。
(2) チーム管理者でログインしたうえで、管理コンソールから「コンテンツ」タブを開きアーカイブ機能があるか確認する
2018 年リリースの team space にはチームフォルダのアーカイブ機能がありません。「アーカイブ済み」という表示の切り替え機能があれば updated team space であることが判定できます。
updated team space での Dropbox API 変更点
2023 年にリリースされた updated team space では、Dropbox API 観点では 3 つの変更点に対応いただく必要があります。
- チームメンバー フォルダ導入に伴うパス変更に対する対応
- チームフォルダ API への対応
- root_info の値の変更
アプリケーションを移行される場合にはそれぞれ構成ごとに次の対応が必要となります。
| アプリ種別 | 対応内容 |
|---|---|
| 2017 年リリースの no team space 向けアプリ |
|
| 2018 年リリースの team space 向けアプリ なお、チームフォルダの作成・削除など管理者向けの機能を有さないアプリケーションの場合は対応不要です |
|
また、どの構成でも動作するように構成情報を確認した上で適切な処理を行う方法も後述します。
チームメンバー フォルダ導入に伴うパス変更に対する対応
個人用ファイル・フォルダとチームフォルダが分離されることに伴い、パス構成が変更されます。どのフォルダのファイルを扱いたいかによって、パス指定方法を変更する必要があります。
詳細は「チーム スペースを使用するチームへの対応ガイド」をご参照ください。
チームフォルダ API への対応
updated team space ではチームフォルダの機能が 2017 年リリース no team space と同等の機能として統合されました。チームフォルダを扱う場合にも、2017 年リリース no team space と同じくチームフォルダ用の API を利用する必要があります。
それぞれ利用シーンごとの対応は次の通りです。
| team space (2018年リリース) |
updated team space (2023年リリース) (no team space と同等) |
|
|---|---|---|
| チームフォルダ一覧を取得 | チームのルート ネームスペースを指定して files/list_folder にてフォルダ一覧を取得 | team/team_folder/list にて一覧取得 |
| チーム フォルダ作成 | チームのルート ネームスペースを指定して sharing/share_folder にて作成 | team/team_folder/create API にて作成 |
| チーム フォルダ削除 | チームのルート ネームスペースを指定して sharing/unshare_folder にて共有を解除してから、files/delete_v2 で削除 | 直接の該当APIはありません。 team/team_folder/archive にてアーカイブ後、team/team_folder/permanently_delete で完全に削除することで削除できますが、左記と異なり完全に削除となるためコンテンツは復元できません。 アーカイブ段階でユーザーにはアクセスできなくなりますので、削除まで必要なければアーカイブ操作まででも用途が満たせます。 |
| チーム フォルダを完全に削除 | 上記の削除操作を行った後に、files/permanently_delete にて完全に削除 | team/team_folder/archive にてアーカイブ後、team/team_folder/permanently_delete で完全に削除 |
| チームフォルダの名称変更 | チームのルート ネームスペースを指定して files/move_v2 を利用 | team/team_folder/rename にて名称変更 |
| チームフォルダのアーカイブ | 該当機能なし | team/team_folder/archive にてアーカイブ |
| チームフォルダをアーカイブ状態から復元 | 該当機能なし | team/team_folder/restore にて復元 |
| チーム選択型同期の設定 | チームのルート ネームスペースをチームフォルダの ID として、team/team_folder/update_sync_settings を呼び出す | team/team_folder/update_sync_settings を呼び出す |
root_info の情報
users/get_current_account API ではユーザーのルート ネームスペースなどの情報を取得できます。利用される環境の構成により得られる値が異なります。この値によって処理判定分岐などに利用されている場合は更新いただく必要があります。
以下に構成ごとに root_info の部分だけを抜粋した例を示しました。
| no team space (2017年リリース) |
team space (2018年リリース) |
updated team space (2023年リリース) |
|---|---|---|
|
|
|
|
構成に応じた API の選択
利用される環境の構成を調べた上で適切な API を選択することでどの環境でも適切に動作するように対応可能です。
環境の構成がどうなっているかは
個人ユーザー向けの API users/features/get_values または
チーム向けの API team/features/get_values を使って調べられます。
どちらの API を利用した場合でも distinct_member_home (チーム向けの場合は has_distinct_member_home) と team_shared_dropbox (チーム向けの場合は has_team_shared_dropbox)という値が得られます。
distinct_member_home/has_distinct_member_home はチームメンバー フォルダとして個人フォルダとチームフォルダが分離されているかどうかを示す値です。true の場合は、チームメンバー フォルダを持ち分離されています。false の場合は 2017 年リリースの no team space 構成であることが確定できます。
team_shared_dropbox/has_team_shared_dropbox はチームメンバーのルート ネームスペースがチーム全体で一つだけで共有されているか、チームメンバーごとに別々に管理しているかを示す値です。true の場合はひとつのルートネームスペースを共有していますので、2018年リリースの team space 構成であることが確定できます。
表にまとめると次のとおりです。
| distinct_member_home | team_shared_dropbox | |
|---|---|---|
| no team space (2017年リリース) |
false | false |
| team space (2018年リリース) |
true | true |
| updated team space (2023年リリース) |
true | false |
API users/features/get_values および team/features/get_values は、調べたい機能のタグを指定して結果を得ることができます。distinct_member_home と team_shared_dropbox を調べたい場合には次のように呼び出します。
ユーザー向け users/features/get_values の場合:
curl -X POST https://api.dropboxapi.com/2/users/features/get_values \
--header "Authorization: Bearer <get access token>" \
--header "Content-Type: application/json" \
--data "{\"features\":[{\".tag\":\"distinct_member_home\"},{\".tag\":\"team_shared_dropbox\"}]}"
チーム向け team/features/get_values の場合:
なお、チーム向けの feature 名称の前には has_ がつきますので has_distinct_member_home と API ドキュメント記載の通りに指定してください。
curl -X POST https://api.dropboxapi.com/2/team/features/get_values \
--header "Authorization: Bearer <get access token>" \
--header "Content-Type: application/json" \
--data "{\"features\":[{\".tag\":\"has_distinct_member_home\"},{\".tag\":\"has_team_shared_dropbox\"}]}"
ファイルパス変更
チームメンバー フォルダが導入されることに伴いフォルダのパスが変更されることはすでに説明しました。チームフォルダへのファイル参照・保存処理を行わないアプリケーションの場合、特に変更の必要はありませんが、チームフォルダを含むユーザーがアクセスできる全てのフォルダに対して処理を実施したいアプリケーションでは追加の対応が必要となります。
ファイルパスの起点となるネームスペースをどこに設定するかを指定する Dropbox-API-Path-Root ヘッダの指定は no team space 構成を含む全ての構成で利用できます。
「チーム スペースを使用するチームへの対応ガイド」にも記載していますが、アプリケーションがデフォルトでアクセスできるアクセス範囲は構成や Dropbox-API-Path-Root ヘッダでの指定により異なります。
| no team space 構成のデフォルト アクセススコープ | team space および updated team space 構成のデフォルト アクセススコープ | team space および updated team space 構成でユーザーのルートネームスペースを指定してアクセスする場合 |
 |
 |
 |
| 図 1：チーム フォルダを使用しているチームのスコープ | 図 2：チーム スペースを使用しているチームのスコープ（デフォルト） | 図 3：チーム スペース（と Dropbox-API-Path-Root ヘッダー）を使用しているチームのスコープ |
no team space (2017 年リリース)構成向けのアプリケーションが updated team space (2023 年リリース)構成で処理すると、チームフォルダが参照できなくなるという課題があります。
この課題は Dropbox-API-Path-Root ヘッダを利用し、ユーザーのルートネームスペースを参照してスコープを変更することで解消できます。チームスペースへの移行の際に個人フォルダへの参照・更新ではパスを変更する必要がありますが、チームフォルダが参照できなくなるというトラブルを回避できます。
アプリケーションの処理手順は次のとおりです。
- ユーザーのルート ネームスペースを調べる。具体的には users/get_current_account API の戻り値として、root_info というマップの中から root_namespace_id を取得します。
- ヘッダに Dropbox-API-Path-Root を指定し、値としてルートネームスペースを指定する。値は
{".tag":"root", "root":"ルートネームスペースID"}のように指定します。
より詳細は「チーム スペースを使用するチームへの対応ガイド」をご参照ください。
チームフォルダの作成・変更処理
チームフォルダを作成・変更する場合 team space (2018年リリース)のみ扱いが異なりますので、team space (2018年リリース)構成であるかどうかを判定に利用します。
team space (2018 年リリース)構成であるかどうかは前述の API 個人ユーザー向けの API users/features/get_values の戻り値 team_shared_dropbox またはチーム向けの API team/features/get_values の戻り値 has_team_shared_dropbox から判定できます。
チームフォルダ API の対応で記載した表をこの値を元に書き換えると次の通りになります。
| team_shared_dropbox / has_team_shared_dropbox の値 | true | false |
|---|---|---|
| チームフォルダ一覧を取得 | チームのルート ネームスペースを指定して files/list_folder にてフォルダ一覧を取得 | team/team_folder/list にて一覧取得 |
| チーム フォルダ作成 | チームのルート ネームスペースを指定して sharing/share_folder にて作成 | team/team_folder/create API にて作成 |
| チーム フォルダ削除 | チームのルート ネームスペースを指定して sharing/unshare_folder にて共有を解除してから、files/delete_v2 で削除 | 直接の該当 API はありません。 team/team_folder/archive にてアーカイブ後、team/team_folder/permanently_delete で完全に削除することで削除できますが、左記と異なり完全に削除となるためコンテンツは復元できません。 アーカイブ段階でユーザーにはアクセスできなくなりますので、削除まで必要なければアーカイブ操作まででも用途が満たせます。 |
| チーム フォルダを完全に削除 | 上記の削除操作を行った後に、files/permanently_delete にて完全に削除 | team/team_folder/archive にてアーカイブ後、team/team_folder/permanently_delete で完全に削除 |
| チームフォルダの名称変更 | チームのルート ネームスペースを指定して files/move_v2 を利用 | team/team_folder/rename にて名称変更 |
| チームフォルダのアーカイブ | 該当機能なし | team/team_folder/archive にてアーカイブ |
| チームフォルダをアーカイブ状態から復元 | 該当機能なし | team/team_folder/restore にて復元 |
| チーム選択型同期の設定 | チームのルート ネームスペースをチームフォルダの ID として、team/team_folder/update_sync_settings を呼び出す | team/team_folder/update_sync_settings を呼び出す |
以上のようにファイルパスへの対応および、チームフォルダ API への対応二つについて対応いただくことで構成に関わらず動作するように対応いただけます。
