实现共享云端硬盘支持

本文档介绍如何使用 Google Drive API 在应用中实现共享云端硬盘支持。

共享云端硬盘遵循与“我的云端硬盘”不同的组织、共享和所有权模式。如果您的应用要在共享云端硬盘上创建和管理文件，则必须在应用中实现共享云端硬盘支持。实现的复杂性取决于应用的功能。

首先，当您的应用执行以下操作时，您必须在请求中添加 supportsAllDrives=true 查询参数：

Drive API v3

  • 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

Drive API v2

  • files.get
  • files.list
  • files.insert
  • files.update
  • files.patch
  • files.copy
  • files.trash
  • files.untrash
  • files.delete
  • files.touch
  • children.insert
  • parents.insert
  • changes.list
  • changes.getStartPageToken
  • changes.get
  • permissions.list
  • permissions.get
  • permissions.insert
  • permissions.update
  • permissions.patch
  • permissions.delete

supportsAllDrives=true 参数会告知 Google 云端硬盘，您的应用旨在处理共享云端硬盘上的文件。

读取或修改权限、跟踪更改或跨多个语料库进行搜索的应用需要额外的共享云端硬盘功能。本文档的其余部分重点介绍了执行这些任务所需的其他更改。

搜索共享云端硬盘上的内容

使用 list 资源上的 files 方法查找共享云端硬盘中的用户文件。如需搜索共享云端硬盘，请参阅搜索共享 云端硬盘。

list 方法包含以下特定于共享云端硬盘的查询参数：

  • driveId：要搜索的共享云端硬盘的 ID。

  • corpora：查询所适用的内容项（文件或文档）的正文。 支持的正文包括 user、domain、drive 和 allDrives。为了提高效率，请优先使用 user 或 drive，而不是 allDrives。默认情况下，语料库设置为 user。

  • includeItemsFromAllDrives：是否应在结果中同时包含“我的云端硬盘”和共享云端硬盘内容项。如果未提供或设置为 false，则不会返回共享云端硬盘内容项。

  • supportsAllDrives：请求应用是否同时支持“我的云端硬盘”和共享云端硬盘。如果为 false，则响应中不会包含共享云端硬盘内容项。

以下查询模式特定于共享云端硬盘：

includeItemsFromAllDrives corpora 查询说明
true user 查询用户已访问的文件，包括共享云端硬盘文件和“我的云端硬盘”文件。
true domain 查询共享给网域的文件，包括共享云端硬盘文件和“我的云端硬盘”文件。
true drive 查询指定共享云端硬盘中的所有内容项。必须在请求中指定 driveId。
true allDrives 查询用户已访问的文件以及用户是成员的所有共享云端硬盘。请注意，响应可能包含 incompleteSearch:true，表示此请求未搜索某些语料库。

以下代码示例展示了如何搜索所有共享云端硬盘以及“我的云端硬盘”中的文件：

Python

files = []
page_token = None
while True:
    response = drive_service.files().list(
        q="mimeType='application/vnd.google-apps.folder'",
        spaces='drive',
        corpora='allDrives',
        supportsAllDrives=True,
        includeItemsFromAllDrives=True,
        fields='nextPageToken, files(id, name)',
        pageToken=page_token
    ).execute()
    files.extend(response.get('files', []))
    page_token = response.get('nextPageToken', None)
    if not page_token:
        break

Node.js

let files = [];
let pageToken = null;
do {
  const response = await drive_service.files.list({
    q: "mimeType='application/vnd.google-apps.folder'",
    spaces: 'drive',
    corpora: 'allDrives',
    supportsAllDrives: true,
    includeItemsFromAllDrives: true,
    fields: 'nextPageToken, files(id, name)',
    pageToken: pageToken
  });
  files = files.concat(response.data.files);
  pageToken = response.data.nextPageToken;
} while (pageToken);

Java

List<File> files = new ArrayList<>();
String pageToken = null;
do {
  FileList result = driveService.files().list()
      .setQ("mimeType='application/vnd.google-apps.folder'")
      .setSpaces("drive")
      .setCorpora("allDrives")
      .setSupportsAllDrives(true)
      .setIncludeItemsFromAllDrives(true)
      .setFields("nextPageToken, files(id, name)")
      .setPageToken(pageToken)
      .execute();
  files.addAll(result.getFiles());
  pageToken = result.getNextPageToken();
} while (pageToken != null);

curl

curl -X GET \
  'https://www.googleapis.com/drive/v3/files?corpora=allDrives&includeItemsFromAllDrives=true&supportsAllDrives=true&fields=nextPageToken%2Cfiles(id%2Cname)' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json'

将 ACCESS_TOKEN 替换为应用的 OAuth 2.0 令牌。

跟踪共享云端硬盘上的更改

使用 list 资源上的 changes 方法跟踪共享云端硬盘上的更改。如需了解详情，请参阅跟踪用户和共享 云端硬盘的更改。

list 方法包含以下特定于共享云端硬盘的查询参数：

  • driveId：返回更改的共享云端硬盘。如果指定了此参数，更改 ID 将引用共享云端硬盘中内容项的更改，并提供文件的当前状态。如需引用特定的共享云端硬盘更改，必须同时使用共享云端硬盘 ID 和更改 ID 作为标识符。

  • includeItemsFromAllDrives：是否应在更改列表中包含共享云端硬盘文件或更改。

  • supportsAllDrives：请求应用是否支持共享云端硬盘。如果为 false，则不会返回共享云端硬盘内容项，包括共享云端硬盘和共享云端硬盘中的文件。

以下查询模式特定于共享云端硬盘：

includeItemsFromAllDrives driveId 查询说明
true 否 更改反映了用户已访问的共享云端硬盘内外的文件更改，以及用户是成员的共享云端硬盘的更改。
true 是 更改反映了指定的特定共享云端硬盘及其内部内容项的更改。

以下代码示例展示了如何跟踪共享云端硬盘上的更改：

Python

# 1. Get the start page token for the shared drive.
response = drive_service.changes().getStartPageToken(
    supportsAllDrives=True,
    driveId='SHARED_DRIVE_ID'
).execute()
start_page_token = response.get('startPageToken')

# 2. List changes starting from the page token.
response = drive_service.changes().list(
    pageToken=start_page_token,
    supportsAllDrives=True,
    includeItemsFromAllDrives=True,
    driveId='SHARED_DRIVE_ID'
).execute()
changes = response.get('changes', [])

Node.js

// 1. Get the start page token for the shared drive.
const tokenResponse = await drive_service.changes.getStartPageToken({
  supportsAllDrives: true,
  driveId: 'SHARED_DRIVE_ID'
});
const startPageToken = tokenResponse.data.startPageToken;

// 2. List changes starting from the page token.
const response = await drive_service.changes.list({
  pageToken: startPageToken,
  supportsAllDrives: true,
  includeItemsFromAllDrives: true,
  driveId: 'SHARED_DRIVE_ID'
});
const changes = response.data.changes;

Java

// 1. Get the start page token for the shared drive.
StartPageToken tokenResult = driveService.changes().getStartPageToken()
    .setSupportsAllDrives(true)
    .setDriveId("SHARED_DRIVE_ID")
    .execute();
String startPageToken = tokenResult.getStartPageToken();

// 2. List changes starting from the page token.
ChangeList changesResult = driveService.changes().list(startPageToken)
    .setSupportsAllDrives(true)
    .setIncludeItemsFromAllDrives(true)
    .setDriveId("SHARED_DRIVE_ID")
    .execute();
List<Change> changes = changesResult.getChanges();

curl

# 1. Get the start page token for the shared drive.
curl -X GET \
  'https://www.googleapis.com/drive/v3/changes/startPageToken?supportsAllDrives=true&driveId=SHARED_DRIVE_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json'

# 2. List changes starting from the page token.
curl -X GET \
  'https://www.googleapis.com/drive/v3/changes?pageToken=START_PAGE_TOKEN&supportsAllDrives=true&includeItemsFromAllDrives=true&driveId=SHARED_DRIVE_ID' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Accept: application/json'

替换以下内容：

  • SHARED_DRIVE_ID：共享云端硬盘的 ID。
  • ACCESS_TOKEN：应用的 OAuth 2.0 令牌。
  • START_PAGE_TOKEN：共享 云端硬盘的起始页令牌。

将 SHARED_DRIVE_ID 替换为共享云端硬盘的 ID

在云端硬盘界面中启用共享云端硬盘支持

如需使用云端硬盘界面访问共享云端硬盘内容，请确保您已在 Google Cloud 控制台的 Google Drive API 的云端硬盘界面集成 标签页中勾选共享云端硬盘支持 复选框。如需了解更多 信息，请参阅配置云端硬盘界面集成。

将 Google Picker 与共享云端硬盘搭配使用

Google Picker 支持选择共享 云端硬盘中的内容项。如需详细了解如何在选择器中启用共享云端硬盘支持和添加共享云端硬盘 视图，请参阅Google Picker API。