設定雲端硬碟使用者介面整合

如要在使用者建立或開啟檔案時，於 Google 雲端硬碟中顯示應用程式，您必須先設定雲端硬碟使用者介面 (UI) 整合。您也必須完成設定，才能在 Google Workspace Marketplace 中上架應用程式。

啟用 Drive API

您必須先在 Google Cloud 專案中啟用 Google API，才能使用。您可以在單一 Google Cloud 專案中啟用一或多個 API。

如要開始與 Google 雲端硬碟 UI 整合，您必須啟用 Drive API。這樣您就能使用 API 和 UI 整合功能。

• 在 Google Cloud 控制台啟用 Google Drive API。

  啟用 API

設定雲端硬碟使用者介面整合

1. 在 Google API 控制台中，依序前往「選單」圖示 >「API 和服務」>「已啟用的 API 和服務」。

   前往「已啟用的 API 和服務」

2. 在「API 和服務」資訊主頁底部，按一下「Google Drive API」。Google Drive API 設定頁面隨即顯示。
3. 選取「Drive UI integration」分頁標籤。
4. (選用) 在「Application name」(應用程式名稱) 欄位中輸入名稱。使用者會在雲端硬碟設定的「管理應用程式」分頁中看到應用程式名稱。
5. (選用) 在「Short description」(簡短說明) 欄位中輸入簡短說明。簡短說明會顯示在雲端硬碟設定的「管理應用程式」分頁中。
6. (選用) 在「Long description」(詳細說明) 欄位中輸入完整說明。

7. 上傳一或多個應用程式圖示，以便在使用者連結的雲端硬碟應用程式清單和「選擇開啟工具」內容選單中顯示。圖示應為 PNG 格式，並使用透明背景。圖示最多可能需要 24 小時才會顯示在雲端硬碟中。

   注意：文件圖示已淘汰。應用程式圖示會顯示在捷徑和第三方捷徑檔案旁邊。其他檔案類型則使用一組標準圖示。

8. 如要使用雲端硬碟 UI 的「Open with」選單項目，請在「Open URL」欄位中輸入應用程式的網址。「選擇開啟工具」內容選單會使用這個網址。

   • 這個網址必須包含完整網域名稱，localhost 無效。
   • 這個網址應可供應用程式的目標使用者存取。如果您有多個應用程式版本，例如一個公開發布版本，以及一個僅限特定使用者存取的版本，每個版本都應使用專屬網址。然後為每個版本建立不同的應用程式設定。
   • 您必須先驗證這個網址的擁有權，才能在 Google Workspace Marketplace 上架應用程式。
   • 根據預設，系統會將 state 查詢參數附加至這個網址，以便將資料從雲端硬碟 UI 傳遞至應用程式。如要瞭解 state 參數的內容，請參閱「state 參數」。
   警告：自動顯示 OAuth 2.0 同意畫面的選項已淘汰。請勿勾選這個方塊。應用程式必須啟動所有授權要求。

9. (選用) 在「Default MIME types」(預設 MIME 類型) 和「Default file extensions」(預設副檔名) 欄位中，輸入預設 MIME 類型和副檔名。預設 MIME 類型和副檔名代表應用程式專門開啟的檔案。舉例來說，應用程式可能會開啟內建格式，用於分層和編輯圖片。僅納入標準媒體類型，並確保沒有錯字和拼寫錯誤。如果應用程式只開啟捷徑或第三方捷徑檔案，則可將 MIME 類型留空。

10. (選用) 在「Secondary MIME types」(次要 MIME 類型) 和「Secondary file extensions」(次要副檔名) 欄位中，輸入次要 MIME 類型和副檔名。次要 MIME 類型和副檔名代表應用程式可以開啟，但並非應用程式專屬的檔案。舉例來說，您的應用程式可能是可開啟 PNG 和 JPG 圖片的圖片編輯應用程式。僅納入標準媒體類型，並確保沒有錯字和拼寫錯誤。如果應用程式只開啟捷徑或第三方捷徑檔案，則可將 MIME 類型留空。

    注意：如果使用者安裝了多個可開啟檔案的雲端硬碟應用程式，系統會使用最近安裝的應用程式，直到使用者選擇其他應用程式為止。

11. 如要使用雲端硬碟 UI 的「新增」按鈕，讓使用者透過您的應用程式建立檔案，請勾選「建立檔案」方塊。系統會顯示「New URL」(新網址) 和選填的「Document name」(文件名稱) 欄位。

    • 這個網址必須包含完整網域名稱，localhost 無效。
    • 您必須先驗證這個網址的擁有權，才能在 Google Workspace Marketplace 中上架應用程式。
    • 根據預設，系統會將 state 查詢參數附加至這個網址，以便將資料從雲端硬碟 UI 傳遞至應用程式。如要瞭解 state 參數的內容，請參閱「state 參數」。

12. 在「新網址」欄位中輸入網址。「新增」按鈕會使用這個網址，將使用者重新導向至您的應用程式。

    注意：請將「文件名稱」欄位留空。這個欄位已不再使用。

13. (選用) 如果您希望應用程式開啟 Google Workspace 支援的檔案，請勾選「Importing」(匯入) 方塊。

14. (選用) 如果應用程式必須管理共用雲端硬碟上的檔案，請勾選「Shared drives support」方塊。如要進一步瞭解如何在應用程式中支援共用雲端硬碟，請參閱「實作共用雲端硬碟支援」。

15. 按一下「提交」。

要求 drive.install 範圍

如要讓應用程式顯示在「選擇開啟工具」或「新增」選單中，請要求 https://www.googleapis.com/auth/drive.install 範圍，以便與雲端硬碟 UI 整合。要求這個範圍時，使用者會看到類似下方的對話方塊：

圖 1. 使用雲端硬碟 UI 範圍時的安裝對話方塊。

如要進一步瞭解可為雲端硬碟應用程式要求的範圍，以及如何要求，請參閱「API 專屬授權和驗證資訊」。

注意：如果您將雲端硬碟應用程式發布至 Google Workspace Marketplace，使用者和網域管理員可以直接從 Google Workspace Marketplace 搜尋及安裝應用程式。

state 參數

根據預設，系統會在「開啟網址」和「新增網址」中附加 state 參數，將資料從雲端硬碟 UI 傳遞至應用程式。這個參數包含 JSON 編碼字串，其中含有範本變數和應用程式要求的相關資料。包含的變數取決於使用的網址類型 (「開啟網址」或「新增網址」)：

範本變數	說明	網址應用
{ids}	以半形逗號分隔的檔案 ID 清單，代表要開啟的檔案。	開啟網址
{exportIds}	以半形逗號分隔的檔案 ID 清單，代表要匯出的檔案。只有在開啟 Google Workspace 檔案時才會使用。	開啟網址
{resourceKeys}	JSON 字典，其中包含檔案 ID 和對應的資源金鑰。	開啟網址
{folderId}	上層資料夾的 ID。	新增網址
{folderResourceKey}	上層資料夾的資源金鑰。	新增網址
{userId}	用於識別使用者的設定檔 ID。	開啟網址和新網址
{action}	正在執行的動作。使用開啟網址時，值為 open；使用新網址時，值為 create。	開啟網址和新網址

state 參數採用網址編碼，因此應用程式必須處理逸出字元，並將其剖析為 JSON。應用程式可以偵測 state 參數中的 create 值，驗證建立檔案的要求。

新網址的 JSON 狀態資訊範例

新網址的 state 資訊如下：

{
  "action":"create",
  "folderId":"FOLDER_ID",
  "folderResourceKey":"FOLDER_RESOURCE_KEY",
  "userId":"USER_ID"
}

Open URL 的 JSON 狀態資訊範例

開啟網址的 state 資訊如下：

{
  "ids": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

ID 和資源金鑰用於擷取檔案中繼資料及下載檔案內容。應用程式取得檔案 ID 和存取權杖後，即可檢查權限、擷取檔案中繼資料，並按照 files.get 方法所述下載檔案內容。

注意：所有應用程式 (包括從捷徑和第三方捷徑開啟檔案的應用程式) 都應呼叫 files.get 方法，檢查使用者對文件的權限。當唯讀權限使用者開啟無法編輯或儲存的檔案時，應用程式應提出警告，而不是讓他們花時間編輯，然後在儲存時顯示錯誤。

相關主題

安裝版應用程式必須能夠建立、管理及開啟從雲端硬碟 UI 啟動的操作。詳情請參閱「與雲端硬碟 UI 的『新增』按鈕整合」或「與雲端硬碟 UI 的『選擇開啟工具』內容選單整合」。