建立及管理檔案

本指南說明如何使用 Google Drive API 在 Google 雲端硬碟中建立及管理檔案。

建立檔案

如要在雲端硬碟中建立不含中繼資料或內容的檔案，請使用 files 資源的 create 方法，且不含任何參數。

建立檔案時，這個方法會傳回 files 資源。系統會為檔案指定 kind 的 drive.file、id、「未命名」的 name，以及 application/octet-stream 的 mimeType。uploadType 標示為必要，但預設為 media，因此您實際上不必提供。

如要進一步瞭解雲端硬碟檔案限制，請參閱「檔案和資料夾限制」。

使用 fields 參數

如要指定要在回應中傳回的欄位，可以使用 files 資源的任何方法，設定 fields system 參數。如果省略 fields 參數，伺服器會傳回方法專屬的預設欄位集。舉例來說，list 方法只會傳回每個檔案的 kind、id、name、mimeType 和 resourceKey 欄位。如要傳回不同欄位，請參閱「傳回特定欄位」。

檔案擁有權

使用 Drive API 建立檔案時，擁有權取決於應用程式使用的驗證憑證，如下所示：

  • 使用者帳戶 (OAuth 2.0)：如果應用程式代表使用者進行驗證，該使用者就會成為檔案擁有者。檔案會儲存在「我的雲端硬碟」資料夾或指定資料夾中。這會占用儲存空間配額。

  • 服務帳戶：如果應用程式使用服務帳戶進行驗證，服務帳戶就是檔案擁有者。檔案會儲存在服務帳戶專用的雲端硬碟儲存空間中。除非明確共用，否則檔案不會顯示在其他雲端硬碟儲存空間帳戶中。如果刪除服務帳戶，系統會立即刪除該帳戶擁有的所有檔案。

    如果您使用服務帳戶，但希望特定使用者帳戶擁有檔案，請使用網域範圍授權。這樣一來，服務帳戶就能模擬使用者身分，並代為建立檔案。詳情請參閱「將網域層級的權限委派給服務帳戶」。

如要進一步瞭解檔案權限，請參閱共用檔案、資料夾和雲端硬碟。

產生 ID 以搭配檔案使用

files 資源的 generateIds 方法可讓您預先產生專屬的檔案 ID，以便在 Google 雲端硬碟中建立或複製檔案和資料夾。如果您需要從應用程式控管檔案 ID，而非讓雲端硬碟自動指派，這個做法就非常實用。

您可以使用 count 查詢參數設定產生的 ID 數量。如未設定 count，系統預設會傳回 10 個結果。您最多可要求 1,000 個 ID。

您也可以指定可使用 ID 的space，以及可使用 ID 的項目type。

產生 ID 後，即可透過 id 欄位傳遞至 create 或 copy 方法。確保建立或複製的檔案使用預先決定的 ID。

如果檔案建立或複製成功，後續重試會傳回 409 Conflict HTTP 狀態碼回應，且不會建立重複檔案。

請注意，系統不支援預先產生的 ID，無法用來建立 Google Workspace 檔案，但 application/vnd.google-apps.drive-sdk 和 application/vnd.google-apps.folder MIME 類型除外。同樣地，系統也不支援參照轉換為 Google Workspace 檔案格式的上傳作業。

建立僅含中繼資料的檔案

中繼資料檔案不含任何內容。中繼資料是描述檔案的資料 (例如 name、mimeType 和 createdTime)。name 等欄位與使用者無關，每位使用者看到的內容都相同，但 viewedByMeTime 等欄位則包含使用者專屬的值。

只有中繼資料的檔案範例是 MIME 類型為 application/vnd.google-apps.folder 的資料夾。詳情請參閱「建立及填入資料夾」。另一個例子是捷徑，指向 Google 雲端硬碟上 MIME 類型為 application/vnd.google-apps.shortcut 的另一個檔案。詳情請參閱「建立雲端硬碟檔案的捷徑」。

管理縮圖

縮圖可協助使用者辨識雲端硬碟檔案。雲端硬碟可以自動為常見檔案類型產生縮圖，您也可以提供應用程式產生的縮圖圖片。詳情請參閱「上傳縮圖」。

複製現有檔案

如要複製檔案並套用所有要求的更新，請對 files 資源使用 copy 方法。如要找出要複製的 fileId，請使用 list 方法。

您可以透過修補程式語意套用更新，也就是對資源進行部分修改。您必須在要求中明確設定要修改的欄位。要求中未包含的欄位會保留現有值。詳情請參閱「處理部分資源」。

您可以使用 generateIds 方法，預先設定複製檔案的檔案 ID。詳情請參閱「產生要用於檔案的 ID」。

請注意，您必須使用適當的 Drive API 範圍授權呼叫。如要進一步瞭解雲端硬碟範圍，請參閱「選擇 Google Drive API 範圍」。

限制和注意事項

準備複製檔案時，請注意以下限制和考量事項：

  • 權限：

    • files 資源的 DownloadRestrictionsMetadata 物件會決定誰可以複製檔案。詳情請參閱「禁止使用者下載、列印或複製你的檔案」。
    • capabilities.canCopy 欄位資源會決定使用者是否可以複製檔案。詳情請參閱「瞭解檔案功能」。
    • 建立副本的使用者會成為副本的擁有者。來源檔案的其他共用設定不會複製到新檔案。如果複本是在共用資料夾中建立，則會沿用該資料夾的權限。
    • 複製檔案的擁有權可能會變更，且副本可能不會沿用原始檔案的共用設定。這些設定可能需要重設。

  • 檔案管理：

    • 部分檔案 (例如第三方捷徑) 無法複製。
    • 你只能將檔案複製到一個上層資料夾。不支援指定多個父項。如果未指定 parents 欄位，檔案會從來源檔案繼承任何可探索的父項。
    • 雖然資料夾也是一種檔案，但你無法複製資料夾。 請改為建立目標資料夾，並將現有檔案的 parents 欄位設為目標資料夾。接著，您就可以刪除原始來源資料夾。
    • 除非指定新檔案名稱，否則 copy 方法會產生與原始檔案同名的檔案。
    • 過度使用 copy 可能會導致超出雲端硬碟 API 配額限制。詳情請參閱「用量限制」。

建議您採取下列後續步驟：