チームスペースを使用するチームへの対応ガイド

はじめに

Dropbox では現在、チーム向け Dropbox をチームスペースにアップグレードする作業を進めています。この記事では、チームスペースへのアップグレードで必要となるアプリケーション側での変更について説明します。

チームスペースのための対応が必要かどうかは、アプリケーションの種類によって異なります。影響を受けるアプリケーションで、チームスペースのための対応を実施していない場合、チームスペースにアップグレードしたチームのファイルにアクセスできなくなる可能性があります。

対応が必要なアプリケーションの例を以下に示します。

Dropbox との間で、ファイルのアップロードやダウンロード、ファイルリストの取得、共有リンクの作成など、ファイルの処理を実施するアプリケーション。特に、チームフォルダのファイルにアクセスする必要のあるアプリケーション
チームフォルダを操作するアプリケーション。新しいチームフォルダを作成する、アーカイブする、チーム向け選択型同期の設定を更新するなど

対応が不要なアプリケーションの例を以下に示します。

チームメンバーの招待やグループメンバーの更新など、チームメンバーに対する操作しか実施しないアプリケーション
Dropbox-API-Path-Root ヘッダーを使用してチームスペースのための対応を実施済みであり、 /team/team_folder 以下の API（チームフォルダを作成する API など）を使用しないアプリケーション。
/files または /team/team_folder 以下の Dropbox API を使用していないアプリケーション

チームスペースの概要

チームスペースは、フォルダの見え方をチームメンバー全員で同じにしたいというお客様のご要望を受けて開発された機能です。チームフォルダの場合、同じフォルダを共有しているチームメンバーでも、人によってフォルダ名やフォルダの場所が違ってしまう場合がありました。

またチームフォルダでは、同じような名前の共有フォルダが複数ある場合、どのフォルダがどのプロジェクトのフォルダなのか判別するのが困難でした。たとえば、「プロジェクト X」、「プロジェクト Y」、「プロジェクト Z」というプロジェクトがあり、各プロジェクトに「Design」というフォルダが存在し、各フォルダが Wendy さんに共有されているとしましょう。このとき、Wendy さんには「Design」、「Design (1)」、「Design (2)」という 3 つのフォルダが見えることになりますが、どのフォルダが「Project X」のフォルダなのか区別するのは困難です。

このため Wendy さんは、自分個人の環境でフォルダ名を変更したり、フォルダを移動したりするかもしれません。しかしその結果は、Wendy さん個人の環境にしか反映されないので、チーム全体としての作業効率が低下しかねません。
新たに導入されたチームスペースでは、この混乱を解消するために、フォルダの見え方をチームメンバー全員で同じにしています。このため、新しいチームメンバーがオンボーディングの際に戸惑うこともなくなります。

このように、チームスペースに移行するとチームでの共同作業がスムーズになります。

チームフォルダとチームスペースの違い

チームフォルダを使用しているチームとチームスペースを使用しているチームでは、フォルダ構造と使用する Dropbox API に違いが出ます。
この違いを理解するために、まず Dropbox フォルダがどのように管理されるかを説明します。

Dropbox が管理する、各メンバーのホームフォルダ、共有フォルダ、チームフォルダ、権限が変更されたサブフォルダは、名前空間と呼ばれます。たとえば、メンバーフォルダ以下に作成された共有フォルダ、チームによって共有されたチームフォルダ、およびそのサブフォルダは、以下の図にあるように名前空間と呼ばれます。

チームフォルダを使用するチームでは、ホーム名前空間はユーザーには表示されません。
共有されていないフォルダは通常のフォルダとして管理され、名前空間としては管理されません。
共有フォルダは名前空間として管理されます。
チームフォルダは名前空間として管理されます。
メンバーが追加されているなど、権限が上位フォルダから変更されているフォルダは名前空間として管理されます。
メンバーが追加されているなど、権限が上位フォルダから変更されているフォルダは名前空間として管理されます。

チームフォルダを使用している場合、チームメンバーのホームフォルダとチームフォルダの間に親子関係はなく、両者は並列のフォルダとして扱われます。チームフォルダへのアクセス権を付与されているメンバーの環境では、チームフォルダはそのメンバーのホームフォルダ以下にマウントされます。

共有フォルダとチームフォルダ以下の名前空間は、メンバーが自由に名前を変更し、別の場所に移動することができます。このため、似たような名前の共有フォルダが複数ある場合、それらを自由に整理できます。しかし、それによってフォルダ構造が他のメンバーと違ってしまい、共同作業のときに混乱が生じる可能性があります。

チームスペースにアップグレードすると、チームに属する名前空間はすべてチームのルート名前空間以下に移動します。ルート名前空間は特殊な名前空間で、ユーザーインターフェースには表示されません。
チームスペースの場合、チームメンバーのホームフォルダには各メンバーの名前が付けられます。このため、個人用のファイルおよびフォルダと、チームによって共有されたファイルおよびフォルダを区別しやすくなります。また、メンバーがホームフォルダ以下のフォルダを共有した場合でも、そのフォルダは引き続きチームメンバーフォルダ以下の名前空間として管理されます。

チームフォルダは、管理者のみが作成、管理できる特殊なフォルダです。チームスペースにアップグレードすると、チームフォルダはトップレベルフォルダと呼ばれる通常のフォルダになり、メンバーも自分自身で作成できるようになります（管理者だけが管理できるよう設定を変更することもできます）。

つまり管理者と、権限を付与されたすべてのメンバーが、通常のフォルダ操作と同じ方法でフォルダを作成し、ファイルを管理できるということです。権限を付与されていないフォルダは、制限付きフォルダとして表示されます。

チームフォルダを使用している場合、管理者はそのフォルダをアーカイブフォルダに指定して共有を停止することができます。一方、チームスペースにアーカイブ機能はなく、この点では通常の共有フォルダと同じように扱われます。チームフォルダからチームスペースにアップグレードすると、既存のアーカイブフォルダは、権限が設定されていない制限付きフォルダに変更されます。

チームフォルダを使用しているチームとチームスペースにアップグレードしたチームの違いをまとめると、以下のようになります。

チームフォルダを使用しているチーム	チームスペースを使用しているチーム
ホームフォルダには、個人用フォルダ、共有フォルダ、チームフォルダが混在する	個人用フォルダは、チームメンバーフォルダとは別のフォルダとして扱われる
チームフォルダ（管理者が管理可能）	トップレベルフォルダ（管理者または権限を付与されたすべてのチームメンバーが管理可能）
アーカイブされたチームフォルダ	権限が設定されていない制限付きフォルダ

Dropbox API とチームスペース

チームフォルダを使用するチームとチームスペースを使用するチームには、ここまで述べてきた違いのほか、ファイルアクセスに関する違いもあります。
ここでは、ファイルアクセスに関する違いと、Dropbox API を使用している場合のアップグレード方法について説明します。

アップグレードの際には、以下の 4 つの違いに対応する必要があります。

スコープとチームメンバーフォルダ
個人用フォルダをチームメンバーフォルダに移行する際に生じるパスの変更
チームフォルダとトップレベルフォルダの違い（フォルダの作成、削除、名前変更などの操作）
追加の OAuth スコープ

ファイルアクセスのスコープ

Dropbox API は、アプリケーションがアクセスできるフォルダのスコープを暗黙的に設定します。スコープの設定は、アプリケーション登録時のアプリケーションタイプの指定と似ています。アプリケーションタイプとして「アプリフォルダ」を選択した場合、ファイルへのアクセスは、ユーザーのアプリフォルダ以下にあるアプリごとのフォルダに制限されます。一方、「Dropbox へのフルアクセス権」を選択した場合は、ユーザーのホーム名前空間へのファイルアクセスが認められます。

チームフォルダを使用しているチームの場合、ホーム名前空間の下に個人用フォルダとチームフォルダが混在するため、アクセスタイプが「Dropbox へのフルアクセス権」であるアプリケーションは両方のフォルダにアクセスできます。これに対し、チームスペースを使用しているチームのアクセスは、ホーム名前空間以下の個人用フォルダに制限されます。トップレベルフォルダにアクセスするためには、スコープの変更が必要です。

スコープ外のファイルとフォルダへのアクセスは許可されず、それらは見つからないものとして扱われます。ファイルやフォルダを個別に識別するファイル ID を使用した場合も同様です。


図 1：チームフォルダを使用しているチームのスコープ	図 2：チームスペースを使用しているチームのスコープ（デフォルト）	図 3：チームスペース（と Dropbox-API-Path-Root ヘッダー）を使用しているチームのスコープ

図 1 は、チームフォルダを使用しているチームのアプリケーションでアクセス可能な範囲を示しています。個人用フォルダとチームフォルダが混在し、両フォルダがそのメンバーのルート名前空間に属しています。
図 2 は、チームスペースを使用しているチームのアプリケーションがデフォルトでアクセス可能な範囲を示しています。スコープは、チームメンバーのホームフォルダ以下に制限されています。
図 3 は、チームスペースを使用しつつ、 Dropbox-API-Path-Root でチームのルート名前空間を指定しているチームのアプリケーションでアクセス可能な範囲を示しています。トップレベルフォルダと個人用フォルダの両方がアクセス可能になっています。

スコープを変更する手順は以下のとおりです。

チームの root_namespace_id を取得します。
Dropbox-API-Path-Root ヘッダーを使用して、ファイルへのアクセス時にルート名前空間を指定します。

チームの root_namespace_id を取得する方法は以下のとおりです。 /users/get_current_account のレスポンスから root_namespace_id を取得します。


　 {
      ...
      "root_info": {
        ".tag": "team",
        "root_namespace_id": "2537566656",
        "home_namespace_id": "2620045633",
        "home_path": "/Wendy"
      }
    }

ルート名前空間の ID を取得するには、レスポンスの JSON データに含まれる root_info の情報を使用します。

チームスペースを使用するチームの場合、 root_namespace_id はチームのルート名前空間を示し、 home_namespace_id は対応するユーザーのホーム名前空間を示します。

チームフォルダを使用するチームの場合、 root_namespace_id と home_namespace_id は同じです。チームスペースに対応した後でトップレベルフォルダとチームメンバーフォルダの両方にアクセスしたい場合は、 root_namespace_id を参照することでいつでも必要なスコープを取得できます。

このため、アプリケーションのユーザーが、チームフォルダを使用するチームのメンバーであるか、チームスペースを使用するチームのメンバーであるかに関係なく、スコープを指定する方法も用意されています。

レスポンスの JSON データに含まれる root_info データの概要を以下にまとめます。

	チームフォルダを使用しているチーム	チームスペースを使用しているチーム
`.tag`	`user`	`team`
`root_namespace_id`	チームメンバーのホーム名前空間の名前空間 ID	チームのルート名前空間の名前空間 ID
`home_namespace_id`	チームメンバーのホーム名前空間の名前空間 ID	チームメンバーのホーム名前空間の名前空間 ID
`home_path`	レスポンスには記述されない	チームのルート名前空間から取得したホーム名前空間へのパス

この結果得られる root_namespace_id は、API リクエストの Dropbox-API-Path-Root ヘッダーを使用して、以下のように指定できます。

 
curl -X POST https://api.dropboxapi.com/2/files/list_folder \
    --header 'Authorization: Bearer <token>' \
    --header 'Dropbox-API-Path-Root: {".tag": "root", "root": "2537566656"}' \
    --header "Content-Type: application/json" \
    --data '{"path":""}'

ファイルパス

スコープがチームのルート名前空間に変更された場合は、メンバーのホーム名前空間以下のファイルにアクセスする際にパスを変更する必要があります。

ホーム名前空間以下のファイルにアクセスする際は、前述のように /users/get_current_account で取得した home_path を使用してパスを指定します。

以下に示したのは、Dropbox Java SDK を使用して、ここまでに説明した内容を実行するコード例です。ホーム名前空間以下のファイルをトップレベルフォルダにコピーするプロセスは、以下のように実装できます。


    public class TeamSpace {
        private static final String ACCESS_TOKEN = "YOUR_TOKEN_HERE";
    
        // エントリを処理（フォルダ名を出力）
        private static void processEntry(Metadata metadata) {
            if (metadata instanceof FolderMetadata) {
                FolderMetadata folderMetadata = (FolderMetadata) metadata;
                System.out.println(folderMetadata.getName());
            }
        }
        public static void main(String[] args) throws Exception {
            DbxRequestConfig config = DbxRequestConfig.newBuilder("team_space").build();
            DbxClientV2 clientBase = new DbxClientV2(config, ACCESS_TOKEN);
    
            // ルート名前空間の情報を取得
            FullAccount currentAccount = clientBase.users().getCurrentAccount();
    
            // Dropbox-API-Path-Root を持つクライアント
            DbxClientV2 client = clientBase.withPathRoot(PathRoot.root(currentAccount.getRootInfo().getRootNamespaceId()));
    
            // フォルダのリストを取得
            ListFolderResult result = null;
            result = client.files().listFolderBuilder("").start();
            result.getEntries().stream().forEach(TeamSpace::processEntry);
            while (result.getHasMore()) {
                String cursor = result.getCursor();
                result = client.files().listFolderContinue(cursor);
                result.getEntries().stream().forEach(TeamSpace::processEntry);
            }
        }
    }

トップレベルフォルダにアクセスする必要がない場合に、引き続きホームフォルダのファイルにアクセスするには、Dropbox-API-Path-Root ヘッダーを省略するだけです。

チームフォルダ

前述したように、チームフォルダは特殊なフォルダです。チームフォルダは管理者のみが作成でき、作成には管理コンソールを使用します。
Dropbox API にも、team/team_folder 以下に特殊な API が用意されています。この API を実行するには管理者権限が必要です。

一方、チームスペースのトップレベルフォルダは、通常の共有フォルダと同じように操作できます。すべてのメンバーがトップレベルフォルダの作成を許可されている場合は、sharing/share_folder で共有フォルダを作成する場合と同じ方法でトップレベルフォルダを使用できます。違いは、前述のように、Dropbox-Path-API-Root を指定する必要があることです。

メモ：

メモ：
チームスペース構成では `team/team_folder` 以下の API は一部の例外を除いて利用することができません。詳細はこちらをご参照ください（英語）。また、共有フォルダ数には上限があるケースがあります。このため、サブフォルダの作成に関しましては、`files/create_folder` の利用もご検討ください。各種推奨値はこちらの記事をご参照ください。

チームスペース構成では team/team_folder 以下の API は一部の例外を除いて利用することができません。詳細はこちらをご参照ください（英語）。
また、共有フォルダ数には上限があるケースがあります。このため、サブフォルダの作成に関しましては、files/create_folder の利用もご検討ください。各種推奨値はこちらの記事をご参照ください。

トップレベルフォルダの管理が管理者だけに制限されている場合は、管理者として API を実行します。その際、Dropbox-API-Select-Admin ヘッダーで管理者のチームメンバー ID を指定します。
管理者のチームメンバー ID は次の方法で取得できます。

/members/list でメンバーのリストを取得し、チーム管理者を選択します。
管理者のメールアドレスがわかっている場合は、/members/get_info を使用してチーム管理者の情報を取得します。
/token/get_authenticated_admin を使用して、そのアプリケーションを許可した管理者の ID を取得します。該当の管理者がすでに管理者ではなくなっている場合、またはそのアカウントが削除されている場合は、権限が不十分だとしてエラーが返されます。

チームフォルダを使用しているチームとチームスペースを使用しているチームでは、使用する API が異なります。このため、現在のチームがチームフォルダを使用しているチームかチームスペースを使用しているチームかを判別する必要があります。

チームがリンクしたアプリを使用している場合は、/team/features/get_values エンドポイントを使用して、has_team_shared_dropbox のブール値を確認します。値が true の場合、そのチームはチームスペース構成を使用しています。
ユーザーがリンクしたアプリを使用している場合は、/users/get_current_account を呼び出し、返される RootInfo のタイプをチェックして、そのユーザーが、チームスペース構成を使用しているチームのメンバーかどうかを確認します。チームがチームスペース構成を使用していない場合、返される root_info は UserRootInfo（.tag は user）となり、チームがチームスペース構成を使用している場合は、TeamRootInfo（.tag は team）となります。
/team/team_folder/list を呼び出すと、チームがチームスペースを使用している場合に、is_team_root のブール値が true に設定されたチームフォルダが 1 つ返されます。

これらの違いを踏まえて、チームフォルダまたはトップレベルフォルダを作成するコードの例を以下に示します。

    
	public class TeamFolderAndTopLevelFolder {
        private static final String ACCESS_TOKEN = "YOUR_TOKEN_HERE";
    
        private static void createTopLevelFolder(DbxTeamClientV2 client, String folderName) throws DbxException {
            // 管理者ユーザーを確認
            TokenGetAuthenticatedAdminResult tokenGetAuthenticatedAdminResult = client.team().tokenGetAuthenticatedAdmin();
            String teamAdminMemberId = tokenGetAuthenticatedAdminResult.getAdminProfile().getTeamMemberId();
    
            // クライアントを管理者として作成
            DbxClientV2 clientAsAdmin = client.asAdmin(teamAdminMemberId);
    
            // ルート名前空間の情報を取得
            FullAccount currentAccount = clientAsAdmin.users().getCurrentAccount();
    
            // Dropbox-API-Path-Root を持つクライアント
            DbxClientV2 clientAsAdminWithRoot = clientAsAdmin.withPathRoot(PathRoot.root(currentAccount.getRootInfo().getRootNamespaceId()));
    
            // フォルダを共有し、新しいトップレベル フォルダを作成
            clientAsAdminWithRoot.sharing().shareFolder("/" + folderName);
        }
    
        private static void createTeamFolder(DbxTeamClientV2 client, String folderName) throws DbxException {
            client.team().teamFolderCreate(folderName);
        }
    
        private static void createTopLevelOrTeamFolder(DbxTeamClientV2 client, String folderName) throws Exception {
            // チームがチーム フォルダを使用しているかチーム スペースを使用しているかを確認
            FeaturesGetValuesBatchResult hasTeamSharedDropbox = client.team().featuresGetValues(List.of(Feature.HAS_TEAM_SHARED_DROPBOX));
    
            Optional<FeatureValue> hasTeamSharedDropboxVal = hasTeamSharedDropbox.getValues().stream().findFirst();
    
            if (hasTeamSharedDropboxVal.isEmpty()) {
                throw new Exception("No feature value");
            } else if (hasTeamSharedDropboxVal.get().getHasTeamSharedDropboxValue().getHasTeamSharedDropboxValue()) {
                // チームがチーム スペースを使用している場合はトップレベル フォルダを作成
                createTopLevelFolder(client, folderName);
            } else {
                // チームがチーム フォルダを使用している場合はチーム フォルダを作成
                createTeamFolder(client, folderName);
            }
        }
    
        public static void main(String[] args) throws Exception {
            DbxRequestConfig config = DbxRequestConfig.newBuilder("list").build();
            DbxTeamClientV2 client = new DbxTeamClientV2(config, ACCESS_TOKEN);
    
            createTopLevelOrTeamFolder(client, "Design Team");
        }
    }