本文說明如何使用 Google Picker API，將 Google Picker 整合至網路應用程式。
Google Picker API 是一種 JavaScript API，可讓您實作這項 API，讓使用者透過 Google Picker 選取或上傳 Google 雲端硬碟檔案。使用者可以授權應用程式存取自己的雲端硬碟資料，以安全且經過授權的方式與檔案互動。
功能
Google 挑選器提供多項功能：
- 與 Google 雲端硬碟使用者介面相似的外觀和風格。
- 多個檢視畫面，顯示雲端硬碟檔案的預覽畫面和縮圖。
- 預先篩選的檢視畫面，只顯示特定檔案類型 (例如 PDF 或圖片) 或特定資料夾。
- 內嵌模式視窗，使用者不必離開主要應用程式。
請注意，雖然您可以使用 Google 挑選器選取及上傳檔案，但使用者無法透過挑選器整理、移動或複製檔案。如要管理檔案，必須使用 Google Drive API 或 雲端硬碟使用者介面。
必要條件
使用 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 控制台中，依序前往「Menu」(選單) >「APIs & Services」(API 和服務) >「Credentials」(憑證)。
- 依序按一下「建立憑證」>「API 金鑰」。
- 系統會顯示新的 API 金鑰。
- 按一下「複製」圖示 ，即可複製 API 金鑰，在應用程式的程式碼中使用。您也可以在專案憑證的「API 金鑰」部分找到 API 金鑰。
- 為避免未經授權的使用行為，建議您為可使用該 API 金鑰的 API 及使用位置新增限制。詳情請參閱「新增 API 限制」。
授權網頁應用程式的憑證
如要驗證使用者身分並存取應用程式中的使用者資料，您需要建立一或多個 OAuth 2.0 用戶端 ID。Google 的 OAuth 伺服器會使用用戶端 ID 來識別個別應用程式。如果您的應用程式是在多個平台中運作，每個平台都會需要專屬的用戶端 ID。- 在 Google API 控制台中，依序前往「Menu」(選單) >「Google Auth platform」(Google 驗證平台) >「Clients」(用戶端)。
- 按一下「Create Client」(建立用戶端)。
- 依序點選「Application type」(應用程式類型) >「Web application」(網頁應用程式)。
- 在「名稱」欄位中輸入憑證名稱。這個名稱只會顯示在 Google API 控制台。
- 新增與應用程式相關的授權 URI：
- 用戶端應用程式 (JavaScript)：在「已授權的 JavaScript 來源」下方，按一下「新增 URI」。然後輸入要用於瀏覽器要求的 URI。這會識別應用程式可從哪些網域將 API 要求傳送至 OAuth 2.0 伺服器。
- 伺服器端應用程式 (Java、Python 等)：按一下「已授權的重新導向 URI」下方的「新增 URI」。然後輸入端點 URI，OAuth 2.0 伺服器可將回應傳送至該 URI。
- 按一下 [Create] (建立)。
新建立的憑證會顯示在「OAuth 2.0 Client IDs」下方。
請記下用戶端 ID。網頁應用程式不會使用用戶端密鑰。
重要事項：建立 Picker 物件時，應用程式必須傳送 OAuth 2.0 存取權杖，以及存取私人使用者資料的檢視畫面。如要要求存取權杖，請參閱「使用 OAuth 2.0 存取 Google API」。
管理 Google 挑選工具
本文的其餘部分將說明如何從網頁應用程式載入及顯示 Google 挑選器，以及如何實作回呼。如要查看完整程式碼範例，請參閱「在 Web 應用程式中使用 Google Picker API 功能」。
載入 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() {
// 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：視您需要的存取層級而定，您必須要求一或多個 OAuth 2.0 範圍，才能存取 Google API。詳情請參閱「Google API 適用的 OAuth 2.0 範圍」。
google.accounts.oauth2 JavaScript 程式庫可協助您提示使用者同意，並取得存取權杖來處理使用者資料。initTokenClient 方法會使用網頁應用程式的用戶端 ID 初始化新的權杖用戶端。詳情請參閱「使用權杖模型」。
onApiLoad 函式會載入 Google 選擇器程式庫。Google 選擇器程式庫成功載入後，系統會呼叫 onPickerApiLoad 回呼函式。
注意：如果您使用 TypeScript，可以安裝 @types/google.picker 來使用 window.google.picker。如要回報這些類型的問題，請建立支援單。
顯示 Google 挑選器
createPicker 函式會確保 Google Picker API 載入完成，並建立 OAuth 2.0 權杖。使用 PickerBuilder.setAppId 方法，透過雲端專案編號設定 Drive 應用程式 ID，允許應用程式存取使用者的檔案。接著，這個函式會建立 Google Picker 的例項並顯示：
// Create and render a Google Picker object for selecting from Drive.
function createPicker() {
const showPicker = () => {
// Replace with your API key and App ID.
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: ''});
}
}
更改下列內容：
API_KEY：您的 API 金鑰。APP_ID：您的雲端專案編號。
如要建立 Google Picker 執行個體，您必須使用 PickerBuilder 建立 Picker 物件。PickerBuilder 會採用 View、OAuth 2.0 權杖、開發人員金鑰，以及成功時要呼叫的回呼函式 (pickerCallback)。
Picker 物件一次會算繪一個 View。請指定至少一個檢視區塊，方法是使用 ViewId (google.picker.ViewId.*)，或是建立 DocsView 的執行個體，進一步控管檢視區塊的算繪方式。
如果 Google 挑選器中新增多個檢視畫面，使用者可以點選左側的分頁，在檢視畫面之間切換。分頁可以與 ViewGroup 物件邏輯分組。
如需有效檢視區塊的清單，請參閱 Google Picker 參考資料中的 ViewId。如要取得任何檢視區塊的權杖，請使用 https://www.googleapis.com/auth/drive.file 範圍。
實作 Google Picker 回呼
Google 挑選器回呼可用於回應 Google 挑選器中的使用者互動，例如選取檔案或按下「取消」。ResponseObject 介面會傳達使用者選取項目相關資訊。
// A callback implementation.
function pickerCallback(data) {
let url = 'nothing';
if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
const doc = data[google.picker.Response.DOCUMENTS][0];
url = doc[google.picker.Document.URL];
}
const message = `You picked: ${url}`;
document.getElementById('result').textContent = message;
}
回呼會收到以 JSON 編碼的資料物件。這個物件包含使用者透過 Google 挑選器 (google.picker.Response.ACTION) 執行的Action。如果使用者選取項目，系統也會填入 google.picker.Response.DOCUMENTS 陣列。在本範例中，google.picker.Document.URL 會顯示在主要頁面上。如要瞭解資料欄位的詳細資料，請參閱 ResponseObject 介面。
篩選特定檔案類型
使用 ViewGroup 篩選特定項目。以下程式碼範例顯示「雲端硬碟」子檢視畫面如何只顯示文件和簡報。
const 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)
.setAppId(cloudProjectNumber)
.setCallback(pickerCallback)
.build();
如需有效檢視畫面類型的清單，請參閱 ViewId。
調整 Google 挑選器的外觀
您可以使用 Feature 物件，為各種檢視畫面開啟或關閉功能。如要微調 Google 挑選器視窗的外觀，請使用 PickerBuilder.enableFeature 或 PickerBuilder.disableFeature 方法。舉例來說，如果您只有單一檢視畫面，可能想隱藏導覽窗格 (Feature.NAV_HIDDEN)，讓使用者有更多空間查看項目。
以下程式碼範例說明如何使用這項功能，在試算表搜尋挑選器中搜尋檔案：
const picker = new google.picker.PickerBuilder()
.addView(google.picker.ViewId.SPREADSHEETS)
.enableFeature(google.picker.Feature.NAV_HIDDEN)
.setDeveloperKey(developerKey)
.setCallback(pickerCallback)
.build();