Google Picker API

Google Picker API 是 JavaScript API。您可以在網頁應用程式中使用這個 API，讓使用者選取或選取 上傳 Google 雲端硬碟檔案。使用者可以授權應用程式存取 雲端硬碟資料，可讓使用者以安全且授權的方式與檔案互動。

Google 挑選器可做為「開啟檔案」的介面顯示儲存在雲端硬碟資訊的對話方塊 並具備以下功能：

• 外觀與風格與 Google 雲端硬碟 UI 相似。
• 多種檢視畫面顯示雲端硬碟檔案的預覽畫面和縮圖。
• 內嵌互動視窗，因此使用者絕不會離開主要應用程式。

請注意，Google Picker 不允許使用者管理、移動或複製單一資料夾中的檔案 移至另一個建議使用 Google Drive API 或是使用雲端硬碟 UI

應用程式需求

使用 Google Picker 的應用程式必須遵守所有現有主題 服務條款。最重要的是，您必須正確指定 在您的要求中提及自己

您也必須擁有 Google Cloud 專案。

設定環境

您必須先設定環境，才能開始使用 Google Picker API。

啟用 API

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

• 在 Google Cloud 控制台中，啟用 Google Picker API。

  啟用 API

建立 API 金鑰

API 金鑰是包含大小寫字母、數字的長字串， 底線和連字號，例如 AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe。 這種驗證方式用於匿名存取可公開取得的資料 資料，例如透過「網際網路上的所有使用者」共用的 Google Workspace 檔案 」分享設定。詳情請參閱 使用 API 金鑰進行驗證。

建立 API 金鑰的方法如下：

1. 在 Google Cloud 控制台中，前往「選單」圖示 > API 與服務 >「憑證」。

   前往「憑證」

2. 按一下「建立憑證」> API 金鑰。
3. 系統會顯示您新的 API 金鑰。
   • 按一下「複製」圖示 複製 API 金鑰，以便用於應用程式的程式碼中。API 金鑰也可能是 列在「API 金鑰」部分專案憑證
   • 按一下「限制金鑰」，即可更新進階設定和限制用途 您的 API 金鑰詳情請參閱「套用 API 金鑰限制」一節。

授權網頁應用程式的憑證

如要驗證使用者及存取應用程式中的使用者資料，您必須： 建立一或多個 OAuth 2.0 用戶端 ID。用戶端 ID 可用來識別 單一應用程式傳送至 Google 的 OAuth 伺服器。如果您的應用程式在多個平台上運作 您都必須為每個平台分別建立用戶端 ID。

1. 在 Google Cloud 控制台中，依序點選「選單」圖示 > 「API 與」「服務」 >「憑證」。

   前往「憑證」

2. 依序點選「建立憑證」>「OAuth 用戶端 ID」。
3. 依序點選「應用程式類型」>「網頁應用程式」。
4. 在「名稱」欄位中輸入憑證的名稱。這個名稱只會顯示在 Google Cloud 控制台中。
5. 新增與應用程式相關的已授權 URI：
   • 用戶端應用程式 (JavaScript)：按一下「授權的 JavaScript 來源」下方的「新增 URI」。然後輸入瀏覽器要求的 URI。可識別應用程式可以從哪些網域傳送 API 要求至 OAuth 2.0 伺服器。
   • 伺服器端應用程式 (Java、Python 等)：按一下「已授權的重新導向 URI」下方的「新增 URI」。然後輸入端點 URI，讓 OAuth 2.0 伺服器傳送回應。
6. 點選「建立」。系統隨即會顯示已建立 OAuth 用戶端的畫面，並顯示您的新用戶端 ID 和用戶端密鑰。

   記下用戶端 ID。用戶端密碼不適用於網頁應用程式，

7. 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」之下。

，瞭解如何調查及移除這項存取權。 重要事項：您的應用程式必須傳送 OAuth 2.0 存取權杖，且該權杖須具備存取權 在建立 Picker 物件時，保護使用者的私人資料。如要要求存取權杖，請參閱使用 OAuth 2.0 存取 Google API。

顯示 Google Picker

本指南的其餘部分將說明如何從網頁應用程式載入及顯示 Google Picker。目的地： 查看完整範例，請前往 Google Picker 程式碼範例。

載入 Google Picker 程式庫

如要載入 Google Picker 程式庫，請呼叫 gapi.load() 並提供程式庫名稱和 成功載入後叫用的回呼函式：

    <script>
      let tokenClient;
      let accessToken = null;
      let pickerInited = false;
      let gisInited = false;

      // Use the API Loader script to load google.picker
      function onApiLoad() {
        gapi.load('picker', onPickerApiLoad);
      }

      function onPickerApiLoad() {
        pickerInited = true;
      }

      function gisLoaded() {
        // TODO(developer): Replace with your client ID and required scopes.
        tokenClient = google.accounts.oauth2.initTokenClient({
          client_id: 'CLIENT_ID',
          scope: 'SCOPES',
          callback: '', // defined later
        });
        gisInited = true;
    }
    </script>
    <!-- Load the Google API Loader script. -->
    <script async defer src="https://apis.google.com/js/api.js" onload="onApiLoad()"></script>
    <script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>
    

更改下列內容：

• CLIENT_ID：網頁應用程式的用戶端 ID。
• SCOPES：應用程式存取 Google API 時必須要求的一或多個 OAuth 2.0 範圍 (視所需的存取層級而定)。 詳情請參閱「Google API 適用的 OAuth 2.0 範圍」。

google.accounts.oauth2 JavaScript 程式庫可協助您提示使用者同意聲明，並取得可處理使用者資料的存取權杖。 initTokenClient() 方法會使用網頁應用程式的用戶端 ID 初始化新的權杖用戶端。詳情請參閱使用符記模型的相關說明。

onApiLoad() 函式會載入 Google Picker 程式庫。 系統會在 Google Picker 程式庫之後呼叫 onPickerApiLoad() 回呼函式 載入。

顯示 Google Picker

createPicker() 函式會進行檢查，確保 Google Picker API 完成載入 並建立 OAuth 權杖使用 setAppId 欄位用來設定 雲端硬碟應用程式 ID，允許應用程式存取使用者的檔案。這個函式接著 建立 Google Picker 的執行個體，並顯示該例項：

    // Create and render a Google Picker object for selecting from Drive.
    function createPicker() {
      const showPicker = () => {
        // TODO(developer): Replace with your API key
        const picker = new google.picker.PickerBuilder()
            .addView(google.picker.ViewId.DOCS)
            .setOAuthToken(accessToken)
            .setDeveloperKey('API_KEY')
            .setCallback(pickerCallback)
            .setAppId(APP_ID)
            .build();
        picker.setVisible(true);
      }

      // Request an access token.
      tokenClient.callback = async (response) => {
        if (response.error !== undefined) {
          throw (response);
        }
        accessToken = response.access_token;
        showPicker();
      };

      if (accessToken === null) {
        // Prompt the user to select a Google Account and ask for consent to share their data
        // when establishing a new session.
        tokenClient.requestAccessToken({prompt: 'consent'});
      } else {
        // Skip display of account chooser and consent dialog for an existing session.
        tokenClient.requestAccessToken({prompt: ''});
      }
    }
    

如要建立 Google Picker 執行個體，請建立 Picker 透過 PickerBuilder 擷取物件。 PickerBuilder 會使用 View，也就是 OAuth 權杖 開發人員金鑰，以及成功時要呼叫的回呼函式 (pickerCallback)。

Picker 物件一次會算繪一個 View。請至少指定一個檢視畫面 使用 ViewId (google.​picker.​ViewId.*)，或是建立 類型 (google.​picker.​*View)。依類型指定檢視畫面，以瀏覽其他 掌控檢視畫面的呈現方式

如果您在 Google Picker 中加入多個資料檢視，使用者可以透過下列方式切換檢視畫面： 按一下左側的分頁標籤可以使用 ViewGroup 物件按照邏輯將分頁分組。

注意：如需有效檢視畫面的清單，請參閱 ViewId 的 Google Picker 參考資料。 如要取得這些檢視畫面的符記，請使用 https://www.googleapis.com/auth/drive.file 範圍。

實作 Google Picker 回呼

Google Picker 回呼可用來回應使用者在 Google Picker 中的互動情形，例如 選取檔案或按下 [取消]。Response 物件會傳送使用者選取項目的相關資訊。

    // A simple callback implementation.
    function pickerCallback(data) {
      let url = 'nothing';
      if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
        let doc = data[google.picker.Response.DOCUMENTS][0];
        url = doc[google.picker.Document.URL];
      }
      let message = `You picked: ${url}`;
      document.getElementById('result').innerText = message;
    }
    

回呼會接收 JSON 編碼的 data 物件。這個物件包含 Action敬上 使用者透過 Google Picker (google.picker.Response.ACTION) 執行動作。 如果使用者選取 Document 項目， google.picker.Response.DOCUMENTS 陣列也 。在此範例中，google.picker.Document.URL 顯示在主頁面上。 如要進一步瞭解資料欄位，請參閱 JSON 參考資料。

篩選特定檔案類型

使用 ViewGroup 篩選特定項目。 您可以透過下列程式碼範例，瞭解如何執行「Google 雲端硬碟」子檢視模式只會顯示文件和簡報。

    let picker = new google.picker.PickerBuilder()
        .addViewGroup(
          new google.picker.ViewGroup(google.picker.ViewId.DOCS)
              .addView(google.picker.ViewId.DOCUMENTS)
              .addView(google.picker.ViewId.PRESENTATIONS))
        .setOAuthToken(oauthToken)
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    

敬上 如需有效檢視畫面類型的清單，請參閱 ViewId。

調整 Google Picker 的外觀

您可以使用 Feature 物件開啟或關閉各種檢視畫面的功能。 如要微調 Google Picker 視窗的外觀，請使用 PickerBuilder.enableFeature() 或 PickerBuilder.disableFeature() 函式。舉例來說，如果您只有一個檢視畫面，不妨隱藏 導覽窗格 (Feature.NAV_HIDDEN)，讓使用者有更多空間查看項目。

以下程式碼範例示範了使用這項功能的試算表搜尋選擇器：

     let picker = new google.picker.PickerBuilder()
         .addView(google.picker.ViewId.SPREADSHEETS)
         .enableFeature(google.picker.Feature.NAV_HIDDEN)
         .setDeveloperKey(developerKey)
         .setCallback(pickerCallback)
         .build();
     

以其他語言轉譯 Google Picker

將語言代碼提供給 PickerBuilder，藉此指定 UI 語言 透過 setLocale(locale) 方法處理例項

以下程式碼範例說明如何將語言代碼設為法文：

    let picker = new google.picker.PickerBuilder()
        .addView(google.picker.ViewId.IMAGE_SEARCH)
        .setLocale('fr')
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    

以下是目前支援的語言代碼清單：

af am ar bg bn ca cs

da de el en en-GB es es-419

et eu fa fi fil fr fr-CA

gl gu hi hr hu id is

it iw ja kn ko lt lv

ml mr ms nl no pl pt-BR

pt-PT ro ru sk sl sr sv

sw ta te th tr uk ur

vi zh-CN zh-HK zh-TW zu