導入共用雲端硬碟支援功能

本文說明如何使用 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 雲端硬碟，您的應用程式可處理共用雲端硬碟中的檔案。

如果應用程式會讀取或修改權限、追蹤變更，或在多個語料庫中搜尋，則需要額外的共用雲端硬碟功能。本文的其餘部分將重點說明執行這些工作時所需的其他變更。

搜尋共用雲端硬碟中的內容

使用 files 資源的 list 方法，找出共用雲端硬碟中的使用者檔案。如要搜尋共用雲端硬碟，請參閱「搜尋共用雲端硬碟」。

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 權杖。

追蹤共用雲端硬碟中的變更

在 changes 資源上使用 list 方法，追蹤共用雲端硬碟的變更。詳情請參閱「追蹤使用者和共用雲端硬碟的變更」。

list 方法包含下列共用雲端硬碟專屬的查詢參數：

  • driveId：傳回變更的共用雲端硬碟。如果指定，變更 ID 會參照共用雲端硬碟中項目的變更，提供檔案的目前狀態。如要參照特定共用雲端硬碟變更，必須同時使用共用雲端硬碟 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

在雲端硬碟使用者介面中啟用共用雲端硬碟支援功能

如要使用 Drive UI 存取共用雲端硬碟內容，請務必在 Google Cloud 控制台的 Google Drive API Drive UI 整合分頁中，勾選「共用雲端硬碟支援」方塊。詳情請參閱「設定雲端硬碟 UI 整合」。

透過 Google 挑選工具使用共用雲端硬碟

Google 挑選器支援選取共用雲端硬碟中的項目。如要進一步瞭解如何啟用共用雲端硬碟支援功能，以及在挑選器中新增共用雲端硬碟檢視畫面，請參閱 Google Picker API。