Google Picker API 是一種 JavaScript API，可讓您在網頁應用程式中使用，讓使用者選取或上傳 Google 雲端硬碟檔案。使用者可以授權給應用程式存取自己的雲端硬碟資料，提供安全且經授權與檔案互動的方式。
Google 挑選器可做為「開啟檔案」對話方塊，顯示儲存在雲端硬碟中的資訊，並具備下列功能：
- 外觀和風格與 Google 雲端硬碟 UI 相似。
- 多個檢視畫面會顯示雲端硬碟檔案的預覽和縮圖。
- 內嵌的強制回應視窗，可讓使用者離開主應用程式。
請注意，Google 挑選器不允許使用者整理、移動或複製某個資料夾中的檔案。如要這麼做，您可以使用 Google Drive API 或雲端硬碟 UI。
應用程式需求
使用 Google Picker 的應用程式必須遵守所有現有的《服務條款》。最重要的是，您必須在要求中正確地表明自己的身分。
此外，您還必須擁有 Google Cloud 專案。設定環境
如要開始使用 Google Picker API，您必須設定環境。
啟用 API
使用 Google API 前，請先在 Google Cloud 專案中啟用這些 API。您可以在單一 Google Cloud 專案中啟用一或多個 API，
在 Google Cloud 控制台中，啟用 Google Picker API。
建立 API 金鑰
API 金鑰是長字串，包含大小寫英文字母、數字、底線和連字號，例如 AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe。這種驗證方法會匿名存取公開資料，例如透過「任何網際網路上都能使用這個連結的使用者」共用設定共用的 Google Workspace 檔案。詳情請參閱使用 API 金鑰進行驗證。
建立 API 金鑰的方法如下：
- 在 Google Cloud 控制台中，依序點選「選單」圖示 >「API 和服務」>「憑證」。
- 依序按一下「建立憑證」>「API 金鑰」。
- 畫面上會顯示新的 API 金鑰。
- 按一下「複製」圖示 ，複製要用於應用程式程式碼的 API 金鑰。您也可以在專案憑證的「API 金鑰」部分找到 API 金鑰。
- 按一下「限制金鑰」更新進階設定並限制 API 金鑰的使用情形。詳情請參閱「套用 API 金鑰限制」。
為網頁應用程式提供憑證
如要驗證使用者並存取應用程式中的使用者資料，您必須建立一或多個 OAuth 2.0 用戶端 ID。用戶端 ID 可用來向 Google 的 OAuth 伺服器識別單一應用程式。如果您的應用程式是在多個平台上執行，您就必須為每個平台建立個別的用戶端 ID。
- 在 Google Cloud 控制台中，依序點選「選單」圖示 >「API 和服務」>「憑證」。
- 依序按一下「建立憑證」>「OAuth 用戶端 ID」。
- 依序點選「應用程式類型」>「網頁應用程式」。
- 在「名稱」欄位中，輸入憑證名稱。這個名稱只會顯示在 Google Cloud 控制台中。
- 新增與應用程式相關的已授權 URI：
- 用戶端應用程式 (JavaScript)：在「已授權的 JavaScript 來源」下方，按一下「新增 URI」。然後輸入瀏覽器要求要使用的 URI。此屬性可識別應用程式可從哪些網域向 OAuth 2.0 伺服器傳送 API 要求。
- 伺服器端應用程式 (Java、Python 等)：在「授權的重新導向 URI」下方，按一下「新增 URI」。然後輸入端點 URI，OAuth 2.0 伺服器可將回應傳送至這個 URI。
- 按一下「建立」，畫面上會顯示 OAuth 用戶端已建立的畫面，顯示您的新用戶端 ID 與用戶端密鑰。
記下「用戶端 ID」。用戶端密鑰不可用於網頁應用程式。
- 按一下「OK」(確定)。新建立的憑證會顯示在「OAuth 2.0 用戶端 ID」下方。
Picker 物件時，您的應用程式必須傳送 OAuth 2.0 存取權杖，其中包含存取私人使用者資料的檢視表。如要要求存取權杖，請參閱使用 OAuth 2.0 存取 Google API。
顯示 Google 挑選器
本指南的其餘部分說明如何從網頁應用程式載入及顯示 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 挑選器
下列 createPicker() 函式會檢查以確保 Google Picker API 完成載入，且 OAuth 權杖已建立。這個函式接著會建立並顯示 Google 挑選器的執行個體：
// 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)
.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 執行個體，您必須使用 PickerBuilder 建立 Picker 物件。PickerBuilder 會採用 View、OAuth 權杖、開發人員金鑰，以及要在成功時呼叫的回呼函式 (pickerCallback)。
Picker 物件會一次算繪一個 View。請透過 ViewId (google.picker.ViewId.*) 或建立類型的執行個體 (google.picker.*View) 指定至少一個檢視畫面。依類型指定檢視畫面，以便進一步控制檢視畫面的算繪方式。
如果 Google Picker 新增多個檢視畫面，使用者只要點選左側的分頁，即可切換檢視畫面。使用 ViewGroup 物件即可將分頁按邏輯分組。
實作 Google Picker 回呼
Google Picker 回呼可用來回應使用者在 Google 挑選器中的互動情形，例如選取檔案或按下「取消」。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 物件。這個物件包含使用者透過 Google 挑選器 (google.picker.Response.ACTION) 執行的 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 挑選器視窗的外觀，請使用 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 挑選器
使用 setLocale(locale) 方法將語言代碼提供給 PickerBuilder 執行個體，以指定 UI 語言。
以下程式碼範例說明如何將語言代碼設為法文：
let picker = new google.picker.PickerBuilder()
.addView(google.picker.ViewId.IMAGE_SEARCH)
.setLocale('fr')
.setDeveloperKey(developerKey)
.setCallback(pickerCallback)
.build();
以下是目前支援的語言代碼清單：
afamarbgbncacs |
dadeelenen-GBeses-419 |
eteufafifilfrfr-CA |
glguhihrhuidis |
itiwjaknkoltlv |
mlmrmsnlnoplpt-BR |
pt-PTroruskslsrsv |
swtatethtrukur |
vizh-CNzh-HKzh-TWzu |