执行代码示例

Google API Explorer 会动态生成代码示例。这些代码示例旨在在本地复制和运行。如需查看示例，请点击 API Explorer 侧边栏中的全屏 。下图显示了展开后全屏 API Explorer：

适用于 Google Books API 的 APIs Explorer 全屏面板
图 2：适用于 Google Books API 的 APIs Explorer 全屏面板。

默认情况下，API Explorer 会显示如何使用 c网址 执行请求。 某些 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 中，为 Web 应用创建 OAuth 客户端 ID 凭据，并使用 https://developers.google.com/oauthplayground 作为重定向 URI。
  4. 在 OAuth 2.0 Playground 中，点击 OAuth 2.0 Configuration 。
  5. 选中使用自己的凭据。
  6. 输入第 3 步生成的客户端 ID 和客户端密钥。
  7. 在范围字段中，输入方法使用的作用域，然后点击 Authorize APIs。
  8. （可选）如果系统显示登录屏幕，请选择要使用的帐号。
  9. （可选）如果看到授权屏幕，请点击接受。
  10. 点击交换令牌的授权代码。系统会返回一个令牌。
  11. 在 c网址 代码示例中，将 [YOUR_API_KEY] 替换为第 2 步中生成的 API 密钥：'https://www.googleapis.com/drive/v3/files?key=[YOUR_API_KEY]' \
  12. 在 c网址 代码示例中，将 [YOUR_ACCESS_TOKEN] 替换为第 10 步中生成的访问令牌： --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \

执行代码示例

从命令行执行 c网址 命令。该命令应如下所示：

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 中，为“Web 应用”创建 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 名称。如需查找该名称，请在支持的 Google API 页面上点击您的 API 旁边的版本链接。版本链接会转到 GitHub。API 名称位于页面的中间位置，前面是 googleapis/google-apis-services-。例如，对于 Drive API v3，API_NAME 为 drive。
  • API_VERSION 是 API 在支持的 Google API 页面上的 API 名称下方列出的 API 版本。
  • REVISION 是 API 的 JavaDoc 参考文档中列出的修订版本号。您可以在以下位置找到 JavaDoc 参考文档：https://googleapis.dev/java/google-api-services-API_NAME/latest/index.html
  • CL_VERSION 是客户端库版本。此值也出现在 JavaDoc 参考文档中。
  • 在工作目录中，将代码示例从 API 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

大多数示例都会输出对 STDOUT 的 API 响应（或其他内容）。

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

大多数示例都会输出对 STDOUT 的 API 响应（或其他内容）。

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

大多数示例都会输出对 STDOUT 的 API 响应（或其他内容）。

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

大多数示例都会输出对 STDOUT 的 API 响应（或其他内容）。

示例问题排查

“授权”对话框未显示

API 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 代码在库加载之前尝试调用适用于 JavaScript 的 Google API 客户端库，则会出现“gapi 未定义”错误。请确保只有在客户端库加载后，才能调用引用 gapi 变量的代码。