Google APIs Explorer 會動態產生程式碼範例。這些程式碼範例是專為複製及執行於本機。如要查看範例,請按一下 APIs Explorer 側邊面板中的全螢幕
。下圖顯示已展開的全螢幕 APIs Explorer:![Google Books API 的 APIs Explorer 全螢幕面板](https://developers-dot-devsite-v2-prod.appspot.com/static/explorer-help/guides/images/expanded.png?authuser=3&hl=zh-tw)
根據預設, APIs Explorer 會說明如何使用 cURL 執行要求。部分 API 也可能顯示其他語言 (例如 JavaScript、Java 和 Python) 的範例。
在本機執行程式碼範例
下列分頁說明執行程式碼範例的必要條件和步驟。如要執行程式碼範例,您必須產生並使用自己的授權憑證。如要瞭解如何建立專案並產生憑證,請參閱特定 Google API 的說明文件。
視方法存取的資料類型 (公開或不公開) 而定,憑證會是以下其中一項:
- 如果是公開資料,憑證就是 API 金鑰。
如果是私人資料,憑證可以是包含 OAuth 2.0 用戶端 ID 和用戶端密鑰的
client_secret.json
檔案,或 OAuth 2.0 存取憑證。
cURL
設定
- 請按照 API 說明文件中的操作說明為應用程式建立或選取專案,並啟用 API。
- 在 Cloud Console 中建立 API 金鑰。
- 在 Cloud Console 中,為網頁應用程式建立 OAuth 用戶端 ID 憑證,並使用
https://developers.google.com/oauthplayground
做為重新導向 URI。 - 在「OAuth 2.0 Playground」中,按一下「OAuth 2.0 設定」圖示 。
- 勾選 [使用自己的憑證]。
- 輸入您在步驟 3 中產生的用戶端 ID 和用戶端密鑰。
- 在範圍欄位中,輸入要搭配方法使用的範圍,然後按一下 [授權 API]。
- (選用) 如果畫面上顯示「登入」畫面,請選取要使用的帳戶。
- (選用) 如果畫面上顯示授權畫面,請按一下 [接受]。
- 按一下 [Exchange 權杖授權]。系統會傳回權杖。
- 在 cURL 程式碼範例中,將
[YOUR_API_KEY]
替換成步驟 2 產生的 API 金鑰:'https://www.googleapis.com/drive/v3/files?key=[YOUR_API_KEY]' \
- 在 cURL 程式碼範例中,將
[YOUR_ACCESS_TOKEN]
替換成步驟 10 產生的存取憑證:--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
執行程式碼範例
透過指令列執行 cURL 指令。指令應如下所示:
curl \
'https://www.googleapis.com/drive/v3/files?key=AIzaSyBiKcaoXmVApwnT24hitQG_dwjGvAj6Ddw' \
--header 'Authorization: Bearer ya29.a0ARrdaM_yQn9MWBpJgKPx880BSnRYIizRYIDz0JN9e66nSliIYpqNXmPsvv2ccfplCTG_U4b1' \
--header 'Accept: application/json' \
--compressed
JavaScript
設定
- 請按照 API 說明文件中的操作說明為應用程式建立或選取專案,並啟用 API。
- 在 Cloud Console 中建立 API 金鑰。
- 在 Cloud Console 中為「網頁應用程式」建立 OAuth 用戶端 ID 憑證,並設定已授權的 JavaScript 來源,以識別用來傳送要求的網址 (例如
http://localhost
)。 - 將完整程式碼範例複製到網路伺服器能夠存取的本機檔案,例如
/var/www/html/example.html
。 在程式碼範例中找出用於設定 API 金鑰或用戶端 ID 的行,並將該值替換為步驟 2 和 3 產生的值:
- API 金鑰:
gapi.client.setApiKey(YOUR_API_KEY);
- OAuth 2.0 用戶端 ID:
gapi.client.init({ 'clientId': 'YOUR_CLIENT_ID',
- API 金鑰:
執行程式碼範例
- 在瀏覽器中開啟檔案,例如
http://localhost/example.html
。建議您使用含有偵錯控制台的瀏覽器,例如 Google Chrome。 - (選用) 如果畫面上顯示「登入」畫面,請選取要使用的帳戶。
- (選用) 如果畫面上顯示授權畫面,請按一下 [接受]。偵錯控制台應將方法回應顯示為 JSON 物件。
Java
必要條件
- Java 1.7 以上版本。
- Gradle 7 以上版本。
設定
- 請按照 API 說明文件中的操作說明為應用程式建立或選取專案,並啟用 API。
- 根據方法存取的資料類型,建立 API 金鑰 (公開資料) 或建立 OAuth 2.0 用戶端 ID (私人資料)。
- 將應用程式類型設為「電腦版應用程式」。
- 如果您建立了 OAuth 2.0 用戶端 ID,請下載含有 OAuth 2.0 憑證的 JSON 檔案。這個檔案的名稱與
client_secret_CLIENTID.json
類似,其中CLIENTID
是專案的用戶端 ID。 在工作目錄中執行下列指令,以建立新的專案結構:
$ gradle init --type basic $ mkdir -p src/main/java src/main/resources
如果您已在步驟 2 中建立 OAuth 2.0 用戶端 ID,請將下載的 JSON 檔案重新命名為
client_secret.json
。將重新命名的檔案儲存在您在步驟 5 建立的
src/main/resources
目錄中。在工作目錄中開啟
build.gradle
檔案,並將內容替換為以下內容:apply plugin: 'java' apply plugin: 'application' mainClassName = 'ApiExample' sourceCompatibility = 1.7 targetCompatibility = 1.7 version = '1.0' repositories { mavenCentral() } dependencies { compile 'com.google.api-client:google-api-client:1.23.0' compile 'com.google.oauth-client:google-oauth-client-jetty:1.23.0' API_SPECIFIC_DEPENDENCY }
在
build.gradle
檔案中,將API_SPECIFIC_DEPENDENCY
這一行替換為指示您呼叫的 API 程式碼。以下是 YouTube Analytics API 的範例:compile 'com.google.apis:google-api-services-youtubeAnalytics:v2-rev16-1.23.0'
操作說明如下:
compile 'com.google.apis:google-api-services-API_NAME:API_VERSION- revREVISION-CL_VERSION'
地點:
API_NAME
是 GitHub 上適用於 API 的 API 名稱。如要查看名稱,請在支援的 Google API 頁面上,按一下 API 旁的版本連結。版本連結會前往 GitHub。API 名稱位於頁面的中部,前面加上googleapis/google-apis-services-
。舉例來說,如果是 Drive API 3 版,API_NAME
就是drive
。API_VERSION
是「支援的 Google API」頁面中 API 名稱下方的 API 版本。REVISION
是 API 的 JavaDoc 參考資料中列出的修訂版本編號。JavaDoc 參考資料位於https://googleapis.dev/java/google-api-services-API_NAME/latest/index.html
CL_VERSION
是用戶端程式庫版本。這個值也會顯示在 JavaDoc 參考資料中。- 將工作目錄中的程式碼範例從 APIs Explorer 複製到
src/main/java/ApiExample.java
。(每個範例中的類別名稱為ApiExample
,因此您不需要修改build.gradle
檔案來執行不同的範例。
執行程式碼範例
使用以下指令執行範例:
gradle -q run
範例應執行您的 API 要求,並將回應列印至 STDOUT
。您也可以呼叫呼叫的服務,瞭解寫入資料要求的影響。
Node.js
必要條件
- Node.js
Node.js 適用的 Google API 用戶端程式庫:
- 如果您尚未安裝用戶端程式庫,請執行下列指令:
npm install googleapis --save
- 如果您先前曾安裝用戶端程式庫,建議您更新程式庫,確保使用的最新測試程式庫類別。如要更新用戶端程式庫,請執行下列指令:
npm update googleapis --save
設定
- 請按照 API 說明文件中的操作說明為應用程式建立或選取專案,並啟用 API。
- 根據方法存取的資料類型,建立 API 金鑰 (公開資料) 或建立 OAuth 2.0 用戶端 ID (私人資料)。
- 將應用程式類型設為「電腦版應用程式」。
- 如果您建立了 OAuth 2.0 用戶端 ID,請下載含有 OAuth 2.0 憑證的 JSON 檔案。這個檔案的名稱與
client_secret_CLIENTID.json
類似,其中CLIENTID
是專案的用戶端 ID。 - 將程式碼範例複製到本機檔案中,並修改範例以正確識別 API 金鑰或用戶端密鑰檔案。在範例中,API 金鑰值為
YOUR_API_KEY
,用戶端密鑰檔案的位置是YOUR_CLIENT_SECRET_FILE.json
。
執行程式碼範例
使用以下指令執行範例:
node sample.js
大部分範例會將 API 回應 (或其他內容) 列印至 STDOUT
。
PHP
必要條件
- 使用指令列介面 (CLI) 和 JSON 擴充功能的 PHP 5.4 以上版本。
- 全域安裝的 Composer 依附元件管理工具。
適用於 PHP 的 Google API 用戶端程式庫:
如果您尚未安裝用戶端程式庫,請執行下列指令:
composer require google/apiclient:^2.0
如果您先前曾安裝用戶端程式庫,建議您更新程式庫,確保使用最新的程式庫類別,以便進行程式庫測試。如要更新用戶端程式庫,請執行下列指令:
composer update google/apiclient --with-dependencies
執行程式碼範例
使用以下指令執行範例:
php sample.php
大部分範例會將 API 回應 (或其他內容) 列印至 STDOUT
。
Python
必要條件
- Python 2.7 或 Python 3.5 以上版本
- pip 套件管理工具
適用於 Python 的 Google API 用戶端程式庫:
pip install --upgrade google-api-python-client
使用者授權的
google-auth-oauthlib
和google-auth-httplib2
程式庫:pip install --upgrade google-auth-oauthlib google-auth-httplib2
設定
- 請按照 API 說明文件中的操作說明為應用程式建立或選取專案,並啟用 API。
- 根據方法存取的資料類型,建立 API 金鑰 (公開資料) 或建立 OAuth 2.0 用戶端 ID (私人資料)。
- 將應用程式類型設為「電腦版應用程式」。
- 如果您建立了 OAuth 2.0 用戶端 ID,請下載含有 OAuth 2.0 憑證的 JSON 檔案。這個檔案的名稱與
client_secret_CLIENTID.json
類似,其中CLIENTID
是專案的用戶端 ID。 - 將程式碼範例複製到本機檔案中,並修改範例以正確識別 API 金鑰或用戶端密鑰檔案。在範例中,API 金鑰值為
YOUR_API_KEY
,用戶端密鑰檔案的位置是YOUR_CLIENT_SECRET_FILE.json
。
執行程式碼範例
使用以下指令執行範例:
python sample.py
大部分範例會將 API 回應 (或其他內容) 列印至 STDOUT
。
Ruby
必要條件
- Ruby 2.0 以上版本
Ruby 適用的 Google API 用戶端程式庫:
gem install google-api-client`
設定
- 請按照 API 說明文件中的操作說明為應用程式建立或選取專案,並啟用 API。
- 根據方法存取的資料類型,建立 API 金鑰 (公開資料) 或建立 OAuth 2.0 用戶端 ID (私人資料)。
- 將應用程式類型設為「電腦版應用程式」。
- 如果您建立了 OAuth 2.0 用戶端 ID,請下載含有 OAuth 2.0 憑證的 JSON 檔案。這個檔案的名稱與
client_secret_CLIENTID.json
類似,其中CLIENTID
是專案的用戶端 ID。 - 將程式碼範例複製到本機檔案中,並修改範例以正確識別 API 金鑰或用戶端密鑰檔案。在範例中,API 金鑰值為
YOUR_API_KEY
,用戶端密鑰檔案的位置是YOUR_CLIENT_SECRET_FILE.json
。
執行程式碼範例
使用以下指令執行範例:
ruby sample.rb
大部分範例會將 API 回應 (或其他內容) 列印至 STDOUT
。
排解樣本問題
未顯示授權對話方塊
APIs Explorer 會使用彈出式視窗授予私人資料的存取權。如果您的瀏覽器封鎖彈出式視窗,系統就不會顯示這個彈出式視窗,您也無法授予存取權。
如果在授權畫面中按一下 [允許],表示系統未執行任何操作,請嘗試變更瀏覽器的彈出式視窗設定,以啟用彈出式視窗。
收到 401 或 403 錯誤
如果您在測試範例時收到 401 或 403 錯誤,可能是因為下列其中一項原因造成問題:
- 您的專案未啟用 API。請參閱 API 的操作說明,瞭解如何建立專案並啟用 API。
- 您使用的是錯誤的授權類型 (API 金鑰,而不是 OAuth 2.0)。
- 您目前使用的是 OAuth 2.0,但範圍太小。
- 設定 API 金鑰時,您可以設定限制,避免有人未經授權使用憑證。然而,要求不符合這些限制。 詳情請參閱使用 API 金鑰限制。
收到混合內容的警告訊息
如果您使用 Google Cloud Endpoints,而且您在開發伺服器中執行端點,瀏覽器可能會針對複合型內容發出警告。出現這則警告的原因在於,API Explorer 是透過 HTTPS 載入,但您的 API 在本機執行時,則須透過 HTTP 託管。
如要使用 Chrome 隱藏這則警告,請按照下列步驟啟用含有特殊標記的 Chrome 工作階段:
path/to/chrome --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:port
例如:
/usr/bin/google-chrome-stable --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:8080
建議您只針對本機測試隱藏這則警告。
僅限 JavaScript:未定義 gapi
未定義 JavaScript 程式碼時,系統會產生「gapi 未定義」的 JavaScript 程式碼呼叫 JavaScript 的 Google API 用戶端程式庫。請確保在用戶端程式庫載入後,才會呼叫參照 gapi
變數的程式碼。