設定雲端硬碟 UI 整合

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

啟用 Drive API

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

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

  • 在 Google Cloud 控制台中啟用 Google 雲端硬碟 API。

    啟用 API

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

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

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

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

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

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

    • 此網址必須包含完整網域名稱，localhost 不適用。
    • 這個網址應可供應用程式的指定使用者存取。如果您有多個應用程式版本 (例如一個用於公開發布，另一個用於向特定使用者發布)，每個版本都應使用專屬網址。然後為每個版本建立不同的應用程式設定。
    • 您必須先驗證這個網址的擁有權，才能在 Google Workspace Marketplace 中刊登應用程式。
    • 根據預設，系統會在這個網址中附加 state 查詢參數，以便將資料從 Google 雲端硬碟 UI 傳送至您的應用程式。如要瞭解 state 參數的內容，請參閱「state 參數」。

  9. (選用) 在「預設 MIME 類型」和「預設副檔名」欄位中輸入預設 MIME 類型和副檔名。預設 MIME 類型和副檔名代表應用程式專門用來開啟的檔案。舉例來說，您的應用程式可能會開啟內建格式，以便進行圖片的堆疊和編輯作業。請只加入標準的媒體類型，並確保沒有錯字和拼寫錯誤。如果您的應用程式只會開啟捷徑或第三方捷徑檔案，您可以將 MIME 類型留空白。

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

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

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

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

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

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

  15. 按一下「提交」。

要求 drive.install 範圍

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

Google 雲端硬碟使用者介面的安裝對話方塊。
圖 1. 使用雲端硬碟 UI 的權限時，會顯示安裝對話方塊。

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

state 參數

根據預設，系統會在「開啟」網址和「新」網址後方附加 state 參數，以便將資料從 Google 雲端硬碟 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 的「New」按鈕整合」或「與雲端硬碟 UI 的「Open with」內容選單整合」一文。