Google API Explorer 会动态生成代码示例。这些代码示例旨在在本地复制和运行。如需查看示例,请点击 API Explorer 侧边栏中的全屏
。下图显示了展开后全屏 API Explorer:![适用于 Google Books API 的 APIs Explorer 全屏面板](https://developers.google.cn/static/explorer-help/guides/images/expanded.png?authuser=4&hl=sl)
默认情况下,API Explorer 会显示如何使用 c网址 执行请求。 某些 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 中,为 Web 应用创建 OAuth 客户端 ID 凭据,并使用
https://developers.google.com/oauthplayground
作为重定向 URI。 - 在 OAuth 2.0 Playground 中,点击 OAuth 2.0 Configuration 。
- 选中使用自己的凭据。
- 输入第 3 步生成的客户端 ID 和客户端密钥。
- 在范围字段中,输入方法使用的作用域,然后点击 Authorize APIs。
- (可选)如果系统显示登录屏幕,请选择要使用的帐号。
- (可选)如果看到授权屏幕,请点击接受。
- 点击交换令牌的授权代码。系统会返回一个令牌。
- 在 c网址 代码示例中,将
[YOUR_API_KEY]
替换为第 2 步中生成的 API 密钥:'https://www.googleapis.com/drive/v3/files?key=[YOUR_API_KEY]' \
- 在 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
设置
- 按照 API 文档中的说明为应用创建或选择项目并启用 API。
- 在 Cloud Console 中,创建 API 密钥。
- 在 Cloud Console 中,为“Web 应用”创建 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 名称。如需查找该名称,请在支持的 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
设置
- 按照 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
大多数示例都会输出对 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
设置
- 按照 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
大多数示例都会输出对 STDOUT
的 API 响应(或其他内容)。
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
大多数示例都会输出对 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
变量的代码。