共有ドライブのサポートを有効にする

この記事は、Google Drive™ APIに関する記事を和訳したものです。
原文: Enable shared drive support
元記事のライセンスは CC-BYで、この和訳記事のライセンスは CC-BYです。
自己責任でご利用ください。
和訳した時期は 2019年6月ころです。

あなたのアプリケーション内で共有ドライブをサポートするには、幾つかの変更を行わなければなりません、そうすれば、あなたのアプリは、共有ドライブおよびそれらが含むファイルを作成し、管理することができます。

もしあなたのアプリケーションをアップグレードしなければ、それは後方互換性のある方法で引き続きサポートされるでしょうが、共有ドライブあるいは共有ドライブに含まれるファイルにアクセスすることはできないでしょう。

振る舞いの違い

共有ドライブは、異なる組織、共有、所有権モデルに従っているため、幾つかの操作は、共有ドライブ内のコンテンツでは許可されません。また、パーミッションと所有権に関連するフィールドは、異なる方法で入力されます。

ファイルリソース

次のフィールドは、共有ドライブ内に配置されたファイルにのみ入力されます:

hasAugmentedPermissions — このファイルへの直接のファイルアクセスがすべてのユーザに付与されているかどうか。
capabilities/canDeleteChildren — 現在のユーザが、このフォルダの子を削除できるかどうか。
capabilities/canMoveChildrenOutOfDrive — 現在のユーザが、このフォルダの子を共有ドライブの外側に移動させることができるかどうか。
capabilities/canMoveChildrenWithinDrive — 現在のユーザが、このフォルダの子を共有ドライブ内に移動させることができるかどうか。
capabilities/canMoveItemWithinDrive — 現在のユーザが、この共有ドライブのアイテムを共有ドライブ内に移動させることができるかどうか。
capabilities/canReadDrive — 現在のユーザが、このファイルが所属する共有ドライブへの読み取りアクセス権を持っているかどうか。
capabilities/canTrashChildren — 現在のユーザが、このフォルダの子をゴミ箱に移動させることができるかどうか。
driveId — このファイルが配置されている共有ドライブの ID。
trashingUser — ファイルが明示的にゴミ箱に移動された場合、それをゴミ箱に移動させたユーザ。
trashedTime — アイテムがゴミ箱に移動された時刻。

次のフィールドは、共有ドライブ内に配置されたファイルには入力されません:

permissions — 共有ドライブの ACLの潜在的なサイズにより、パーミッションはファイルの一部として返されません。共有ドライブ内のファイル、あるいは、共有ドライブ自体のパーミッションをリストするには、permissions.list メソッドを使用します、それは、ページネーションをサポートします。
owners, ownerNames, ownedByMe — 共有ドライブ内のファイルは、共有ドライブによって所有されます、個々のユーザではありません。
folderColorRgb — フォルダは、個別に色分けされることはできません。
shared — 共有ドライブ内のすべてのアイテムは共有されています。
writersCanShare — 共有ドライブ内の役割によって共有を制限することは、現在は、できません。

次のフィールドは、ユーザがアイテムにファイルアクセスのパーミッションを付与されているときのみセットされます:

sharedWithMeDate
sharingUser

次のフィールドは、それらを共有ドライブとともに使用するとき、特に注意を必要とします:

parents.isRoot — このフィールドは、My Driveルートフォルダのみが trueです。共有ドライブのトップレベルフォルダでは falseです。
parents — リクエストしているユーザが共有ドライブのメンバではなく、親へのアクセス権を持っていない場合、親は、親のリストに表示されません。さらに、トップレベルフォルダを除いて、親のリストは、ファイルが共有ドライブに配置されている場合、正確にひとつのアイテムを含まなければなりません。
capabilities/canRemoveChildren — capabilities/canDeleteChildrenあるいは capabilities/canTrashChildrenを使用します。

パーミッションリソース

次のフィールドは、共有ドライブ内に配置されたファイルにのみ入力されます:

permissionDetails — この共有ドライブのファイルにある、あるいは、よって継承されている、要約されたパーミッションのリスト。これは、共有ドライブのアイテムにのみ存在する、出力専用のフィールドです。

追加の変更:

2つの新しい役割 organizerおよび fileOrganizerが定義されました。
permissions.listは、今はページネーションをサポートします。

変更リソース

次の新しいフィールドが利用可能です:

changeType — 変更のタイプ。可能な値は、fileおよび driveです。
driveId — この変更に関連した共有ドライブの ID。
drive — 共有ドライブの更新状態。 changeTypeが driveで、そのユーザがまだ共有ドライブのメンバである場合に存在します。

追加の変更が、コンテンツを共有ドライブと同期させる、あるいは、アクティビティを追跡する必要があるアプリケーションでは必要とされるかもしれません。詳細については、ユーザおよび共有ドライブの変更を追跡するを参照してください。

共有ドライブのコンテンツへのオプトイン

共有ドライブに含まれるコンテンツにアクセスするには、あなたのアプリを変更する必要があります。この変更の規模は、あなたのアプリが共有ドライブに関連する振る舞いの変更に影響を受けるかどうかに依存します。

共有ドライブの変更の影響を受けないアプリ

もしあなたのアプリケーションが振る舞いの違いによる影響を受けていなければ、リクエストに supportsAllDrives=trueクエリパラメータを含む必要があるのみです。これは、アプリケーションが共有ドライブに含まれるファイルの振る舞いの違いを認識していることを示しています。

次のメソッドは、共有ドライブのコンテンツを操作するとき、supportsAllDrives=true を必要とします:

files.get
files.list
files.create
files.update
files.copy
files.delete
changes.list
changes.getStartPageToken
permissions.list
permissions.get
permissions.create
permissions.update
permissions.delete

共有ドライブの振る舞いの影響を受けるアプリ

パーミッションを読み取りあるいは修正する、変更を追跡する、あるいは、複数のコーパスを横断して検索する必要があるアプリケーションは、追加の変更を必要とします。次のセクションでは、幾つかのアプリに必要とされる変更についてハイライトします。

共有ドライブのコンテンツを `files.list`に含める

共有ドライブを使用することは、特定の共有ドライブ内のファイルを検索する、あるいは、すべての共有ドライブを横断して検索する機能を追加します。

files.listリクエストは、共有ドライブに固有の幾つかのパラメータを持っています:

driveId — 検索する共有ドライブの ID。
includeItemsFromAllDrives — 共有ドライブのアイテムが結果に含まれるべきかどうか。もし、存在しないあるいは falseにセットされているならば、共有ドライブのアイテムは返されません。備考: 2020年6月1日、このパラメータは無視されるでしょう、そして、すべてのアプリケーションは共有ドライブをサポートすることが想定されます。
corpora — クエリが適用するアイテム(ファイル/ドキュメント)のボディ。サポートされるボディは、user、domain、drive、および allDrivesです。効率性のため、allDrivesよりも userあるいは driveのほうが好ましいです。
supportsAllDrives — リクエストしているアプリケーションが、My Driveと共同ドライブの両方をサポートしているかどうか。もし falseであるならば、共有ドライブのアイテムはレスポンスに含まれません。備考: 2020年6月1日、このパラメータは無視されるでしょう、そして、すべてのアプリケーションは共有ドライブをサポートすることが想定されます。

次のクエリモードは、共有ドライブに固有のものです:

`includeItemsFromAllDrives`	`corpora`	クエリの説明
`true`	`user`	共有ドライブと My Driveのファイルの両方を含む、ユーザがアクセスしたファイルをクエリします。
`true`	`drive`	指定された共有ドライブ内のすべてのアイテムをクエリします。 driveIdがリクエストにて指定されていなければなりません。
`true`	`allDrives`	ユーザがアクセスしたファイル、および、彼らがメンバになっているすべての共有ドライブをクエリします。レスポンスが `incompleteSearch : true`を含むかもしれないことに注意してください、これは、幾つかのコーパスがこのリクエストを検索しなかったことを示しています。
`true`	`domain`	共有ドライブと My Driveのファイルの両方を含む、ドメインと共有されているファイルを食えりします。

共有ドライブ内の変更を追跡する

changes.listメソッドは、共有ドライブに固有の幾つかのパラメータを持っています:

driveId — 変更が返される共有ドライブ。もし指定されているならば、IDは、共有ドライブの変更を参照します、ユーザによって表示されるファイルの変更ではありません。特定の共有ドライブの変更を参照するには、共有ドライブ IDと変更 IDの両方が、識別子として使用されなければなりません。
supportsAllDrives — リクエストするアプリケーションが共有ドライブをサポートしているかどうか。もし falseであるならば、共有ドライブにのアイテムは、共有ドライブと共有ドライブ内のファイルの両方を含み、返されません。
includeItemsFromAllDrives — 共有ドライブのファイルあるいは変更が、変更のリストに含まれるべきかどうか。