執行程式碼範例

Google APIs Explorer 會動態產生程式碼範例。這些程式碼範例是專為複製及執行於本機。如要查看範例，請按一下 APIs Explorer 側邊面板中的全螢幕 。下圖顯示已展開的全螢幕 APIs Explorer：

Google Books API 的 APIs Explorer 全螢幕面板
圖 2：Google Books API 的 APIs Explorer 全螢幕面板。

根據預設， APIs Explorer 會說明如何使用 cURL 執行要求。部分 API 也可能顯示其他語言 (例如 JavaScript、Java 和 Python) 的範例。

在本機執行程式碼範例

下列分頁說明執行程式碼範例的必要條件和步驟。如要執行程式碼範例，您必須產生並使用自己的授權憑證。如要瞭解如何建立專案並產生憑證，請參閱特定 Google API 的說明文件。

視方法存取的資料類型 (公開或不公開) 而定，憑證會是以下其中一項：

  • 如果是公開資料，憑證就是 API 金鑰。

  • 如果是私人資料，憑證可以是包含 OAuth 2.0 用戶端 ID 和用戶端密鑰的 client_secret.json 檔案，或 OAuth 2.0 存取憑證。

cURL

設定

  1. 請按照 API 說明文件中的操作說明為應用程式建立或選取專案，並啟用 API。
  2. 在 Cloud Console 中建立 API 金鑰。
  3. 在 Cloud Console 中，為網頁應用程式建立 OAuth 用戶端 ID 憑證，並使用 https://developers.google.com/oauthplayground 做為重新導向 URI。
  4. 在「OAuth 2.0 Playground」中，按一下「OAuth 2.0 設定」圖示 。
  5. 勾選 [使用自己的憑證]。
  6. 輸入您在步驟 3 中產生的用戶端 ID 和用戶端密鑰。
  7. 在範圍欄位中，輸入要搭配方法使用的範圍，然後按一下 [授權 API]。
  8. (選用) 如果畫面上顯示「登入」畫面，請選取要使用的帳戶。
  9. (選用) 如果畫面上顯示授權畫面，請按一下 [接受]。
  10. 按一下 [Exchange 權杖授權]。系統會傳回權杖。
  11. 在 cURL 程式碼範例中，將 [YOUR_API_KEY] 替換成步驟 2 產生的 API 金鑰：'https://www.googleapis.com/drive/v3/files?key=[YOUR_API_KEY]' \
  12. 在 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

設定

  1. 請按照 API 說明文件中的操作說明為應用程式建立或選取專案，並啟用 API。
  2. 在 Cloud Console 中建立 API 金鑰。
  3. 在 Cloud Console 中為「網頁應用程式」建立 OAuth 用戶端 ID 憑證，並設定已授權的 JavaScript 來源，以識別用來傳送要求的網址 (例如 http://localhost)。
  4. 將完整程式碼範例複製到網路伺服器能夠存取的本機檔案，例如 /var/www/html/example.html。

  5. 在程式碼範例中找出用於設定 API 金鑰或用戶端 ID 的行，並將該值替換為步驟 2 和 3 產生的值：

    • API 金鑰： gapi.client.setApiKey(YOUR_API_KEY);
    • OAuth 2.0 用戶端 ID： gapi.client.init({ 'clientId': 'YOUR_CLIENT_ID',

執行程式碼範例

  1. 在瀏覽器中開啟檔案，例如 http://localhost/example.html。建議您使用含有偵錯控制台的瀏覽器，例如 Google Chrome。
  2. (選用) 如果畫面上顯示「登入」畫面，請選取要使用的帳戶。
  3. (選用) 如果畫面上顯示授權畫面，請按一下 [接受]。偵錯控制台應將方法回應顯示為 JSON 物件。

Java

必要條件

  • Java 1.7 以上版本。
  • Gradle 7 以上版本。

設定

  1. 請按照 API 說明文件中的操作說明為應用程式建立或選取專案，並啟用 API。
  2. 根據方法存取的資料類型，建立 API 金鑰 (公開資料) 或建立 OAuth 2.0 用戶端 ID (私人資料)。
  3. 將應用程式類型設為「電腦版應用程式」。
  4. 如果您建立了 OAuth 2.0 用戶端 ID，請下載含有 OAuth 2.0 憑證的 JSON 檔案。這個檔案的名稱與 client_secret_CLIENTID.json 類似，其中 CLIENTID 是專案的用戶端 ID。

  5. 在工作目錄中執行下列指令，以建立新的專案結構：

    $ gradle init --type basic
$ mkdir -p src/main/java src/main/resources

  6. 如果您已在步驟 2 中建立 OAuth 2.0 用戶端 ID，請將下載的 JSON 檔案重新命名為 client_secret.json。

  7. 將重新命名的檔案儲存在您在步驟 5 建立的 src/main/resources 目錄中。

  8. 在工作目錄中開啟 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
}

  9. 在 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

設定

  1. 請按照 API 說明文件中的操作說明為應用程式建立或選取專案，並啟用 API。
  2. 根據方法存取的資料類型，建立 API 金鑰 (公開資料) 或建立 OAuth 2.0 用戶端 ID (私人資料)。
  3. 將應用程式類型設為「電腦版應用程式」。
  4. 如果您建立了 OAuth 2.0 用戶端 ID，請下載含有 OAuth 2.0 憑證的 JSON 檔案。這個檔案的名稱與 client_secret_CLIENTID.json 類似，其中 CLIENTID 是專案的用戶端 ID。
  5. 將程式碼範例複製到本機檔案中，並修改範例以正確識別 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

設定

  1. 請按照 API 說明文件中的操作說明為應用程式建立或選取專案，並啟用 API。
  2. 根據方法存取的資料類型，建立 API 金鑰 (公開資料) 或建立 OAuth 2.0 用戶端 ID (私人資料)。
  3. 將應用程式類型設為「電腦版應用程式」。
  4. 如果您建立了 OAuth 2.0 用戶端 ID，請下載含有 OAuth 2.0 憑證的 JSON 檔案。這個檔案的名稱與 client_secret_CLIENTID.json 類似，其中 CLIENTID 是專案的用戶端 ID。
  5. 將程式碼範例複製到本機檔案中，並修改範例以正確識別 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`

設定

  1. 請按照 API 說明文件中的操作說明為應用程式建立或選取專案，並啟用 API。
  2. 根據方法存取的資料類型，建立 API 金鑰 (公開資料) 或建立 OAuth 2.0 用戶端 ID (私人資料)。
  3. 將應用程式類型設為「電腦版應用程式」。
  4. 如果您建立了 OAuth 2.0 用戶端 ID，請下載含有 OAuth 2.0 憑證的 JSON 檔案。這個檔案的名稱與 client_secret_CLIENTID.json 類似，其中 CLIENTID 是專案的用戶端 ID。
  5. 將程式碼範例複製到本機檔案中，並修改範例以正確識別 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 變數的程式碼。