設定雲端硬碟 UI 整合

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

啟用 Drive API

使用 Google API 之前，您必須在 Google Cloud 專案中開啟這些 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 整合」分頁標籤。
  4. (選用) 在「Application name」(應用程式名稱) 欄位中輸入名稱。應用程式名稱會在雲端硬碟設定的「管理應用程式」分頁中向使用者顯示。
  5. (選用) 在「Short description」(簡短說明) 欄位中輸入一行簡短的說明。使用者會在雲端硬碟設定中的「管理應用程式」分頁中看到簡短說明。
  6. (選用) 在「詳細說明」欄位中輸入完整說明。

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

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

    • 這個網址必須包含完整的網域名稱；localhost 無法運作。
    • 應用程式的目標使用者應可存取這個網址。若您有多個應用程式版本 (例如一個用於公開發布，另一個則用於受限製版本特定使用者)，則每個版本都應使用不重複的網址。接著，您就能為每個版本建立不同的應用程式設定。
    • 您必須先驗證這個網址的擁有權，才能在 Google Workspace Marketplace 中列出您的應用程式。
    • 根據預設，系統會將 state 查詢參數附加至這個網址，以便將資料從雲端硬碟 UI 傳送至應用程式。如要瞭解 state 參數的內容，請參閱 state 參數。

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

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

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

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

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

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

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

  15. 點選「提交」。

要求 drive.install 範圍

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

Google 雲端硬碟 UI 的安裝對話方塊。
圖 1. 使用雲端硬碟 UI 範圍時，系統會顯示安裝對話方塊。

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

state 參數

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

範本變數 說明 網址應用程式
{ids} 要開啟的檔案 ID 清單 (以半形逗號分隔)。 開啟網址
{exportIds} 以逗號分隔的匯出檔案 ID 清單 (僅在開啟內建的 Google 文件時使用)。 開啟網址
{resourceKeys} 檔案 ID 對應至個別資源金鑰的 JSON 字典。 開啟網址
{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"
}

「開放式網址」的 JSON 狀態資訊範例

開放式網址的 state 資訊為：

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

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

已安裝的應用程式必須要能建立、管理和開啟透過雲端硬碟 UI 啟動的動作。詳情請參閱整合雲端硬碟 UI 的「新增」按鈕或與雲端硬碟 UI 的「開啟工具」內容選單整合。