第三方 API

Google Ads 脚本的一项强大功能是能够与第三方 API 中的数据和服务集成。

本指南介绍了以下概念,可帮助您编写脚本以连接到其他服务:

  • 发出 HTTP 请求:如何使用 UrlFetchApp 访问外部 API。
  • 身份验证:我们介绍了一些常见的身份验证场景。
  • 解析响应:如何处理返回的 JSON 和 XML 数据。

我们还针对一些热门 API 提供了示例,以说明这些概念。

使用 UrlFetchApp 提取数据

UrlFetchApp 提供与第三方 API 交互所需的核心功能。

以下示例展示了如何从 OpenWeatherMap 获取天气数据。我们之所以选择 OpenWeatherMap,是因为它的授权方案和 API 相对简单。

发出请求

OpenWeatherMap 文档指定了请求当前天气的格式,如下所示:

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

该网址提供了我们的第一个授权示例:参数 apikey 是必需的,并且该值对每个用户都是唯一的。此密钥通过注册获取。

注册后,可以使用该密钥发出请求,如下所示:

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

执行此代码后,系统会将一长串 JSON 文本写入 Google Ads 脚本中的日志记录窗口。

下一步是将其转换为可在脚本中使用的格式。

JSON 数据

许多 API 都以 JSON 格式提供响应。这表示 JavaScript 对象的序列化,以便对象、数组和基本类型可以表示为字符串并作为字符串进行传输。

如需将 JSON 字符串(例如从 OpenWeatherMap 返回的字符串)转换回 JavaScript 对象,请使用内置的 JSON.parse 方法。继续前面的示例:

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

JSON.parse 方法会将字符串转换为具有 name 属性的对象。

如需详细了解如何处理不同格式的 API 响应,请参阅解析响应部分。

错误处理

在脚本中使用第三方 API 时,错误处理是一个重要的考虑因素,因为第三方 API 通常会频繁更改并生成非预期响应值,例如:

  • API 的网址或参数可能会在您不知情的情况下发生变化。
  • 您的 API 密钥(或其他用户凭证)可能会过期。
  • 响应格式可能会发生变化,恕不另行通知。

HTTP 状态代码

由于可能会出现非预期响应,因此您应检查 HTTP 状态代码。默认情况下,如果遇到 HTTP 错误代码,UrlFetchApp 将抛出异常。如需更改此行为,必须传递一个可选参数,如以下示例所示:

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

响应结构

当第三方 API 发生变化时,您可能不会立即意识到这些变化可能会影响您的脚本。例如,如果 OpenWeatherMap 示例中返回的 name 属性更改为 locationName,则使用此属性的脚本将失败。

因此,测试返回的结构是否符合预期会很有帮助,例如:

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

使用 UrlFetchApp 发送 POST 数据

使用 OpenWeatherMap 的入门示例仅提取了数据。通常,不会更改远程服务器状态的 API 调用会使用 HTTP GET 方法。

GET 方法是 UrlFetchApp 的默认方法。不过,某些 API 调用(例如对发送短信的服务的调用)需要使用其他方法,例如 POST 或 PUT。

为了说明如何将 POST 调用与 UrlFetchApp 结合使用,以下示例演示了如何与协作消息传递应用 Slack 集成,以向 Slack 用户和群组发送 Slack 消息。

设置 Slack

本指南假定您已注册 Slack 账号。

与上一个示例中的 OpenWeatherMap 一样,您需要获取令牌才能发送消息。Slack 提供了一个唯一的网址,可让您向团队发送消息,称为传入 Webhook。

点击添加传入网络钩子集成并按照说明设置传入网络钩子。该流程应发出一个用于发送消息的网址。

发出 POST 请求

设置传入 Webhook 后,发出 POST 请求需要在传递给 UrlFetchApp.fetch 的 options 参数中使用一些额外属性:

  • method:如前所述,此值默认为 GET,但在这里,我们将其替换并设置为 POST。
  • payload:这是要作为 POST 请求的一部分发送到服务器的数据。在此示例中,Slack 需要一个序列化为 JSON 格式的对象,如 Slack 文档中所述。为此,请使用 [JSON.stringify][json-stringify-url] 方法,并将 Content-Type 设置为 application/json。

      // Change the URL for the one issued to you from 'Setting up Slack'.
      const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
      const slackMessage = {
        text: 'Hello, slack!'
      };
    
      const options = {
        method: 'POST',
        contentType: 'application/json',
        payload: JSON.stringify(slackMessage)
      };
      UrlFetchApp.fetch(SLACK_URL, options);
    

扩展的 Slack 示例

上一个示例展示了在 Slack 中启用收到的消息所需的最少代码。一个扩展示例说明了如何创建广告系列效果报告并将其发送到群组,以及一些格式设置和显示选项。

收到的消息

如需详细了解 Slack 消息,请参阅 Slack 文档中的消息格式设置。

表单数据

前面的示例演示了如何使用 JSON 字符串作为 POST 请求的 payload 属性。

根据 payload 的格式,UrlFetchApp 会采用不同的方法来构建 POST 请求:

  • 如果 payload 是字符串,则字符串参数会作为请求的正文发送。
  • 当 payload 是一个对象(例如值映射)时:

    {to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
    

    键值对会转换为表单数据:

    subject=Test&to=mail@example.com&body=Hello,+World!
    

    此外,请求的 Content-Type 标头设置为 application/x-www-form-urlencoded。

某些 API 要求在提交 POST 请求时使用表单数据,因此请务必记住这种从 JavaScript 对象到表单数据的自动转换。

HTTP 基本身份验证

HTTP 基本身份验证是最简单的身份验证形式之一,许多 API 都会使用。

身份验证是通过在每个请求的 HTTP 标头中附加编码的用户名和密码来实现的。

HTTP 基本身份验证

构建请求

如需生成经过身份验证的请求,您需要执行以下步骤:

  1. 通过使用英文冒号将用户名和密码连接在一起,形成口令,例如 username:password。
  2. 对口令进行 Base64 编码,例如,username:password 变为 dXNlcm5hbWU6cGFzc3dvcmQ=。
  3. 在请求中附加 Authorization 标头,格式为 Authorization: Basic <encoded passphrase>

以下代码段展示了如何在 Google Ads 脚本中实现此目的:

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

基本身份验证示例

代码示例部分包含两个示例,说明了如何使用 HTTP 基本身份验证:

Plivo

Plivo 是一项服务,可帮助您通过其 API 发送和接收短信。此示例演示了如何发送消息。

  1. 向 Plivo 注册。
  2. 将示例脚本粘贴到 Google Ads 中的新脚本中。
  3. 将 PLIVO_ACCOUNT_AUTHID 和 PLIVO_ACCOUNT_AUTHTOKEN 值替换为管理信息中心中的值。
  4. 插入脚本中指定的电子邮件地址,以便接收错误通知。
  5. 如需使用 Plivo,您必须购买号码或向试用账号添加号码。添加可与试用账号搭配使用的沙盒号码。
  6. 同时添加将显示为发送者的号码和接收者号码。
  7. 将脚本中的 PLIVO_SRC_PHONE_NUMBER 更新为刚刚注册的沙盒号码之一。这应包括国际国家/地区代码,例如英国号码的 447777123456。

Twilio

Twilio 是另一项服务,可帮助您通过其 API 发送和接收短信。此示例展示了如何发送消息。

  1. 向 Twillio 注册。
  2. 将示例脚本粘贴到 Google Ads 中的新脚本中。
  3. 将 TWILIO_ACCOUNT_SID 和 TWILIO_ACCOUNT_AUTHTOKEN 值替换为账号控制台页面上显示的值。
  4. 将 TWILIO_SRC_PHONE_NUMBER 替换为信息中心中的号码,这是 Twilio 授权发送消息的号码。

OAuth 1.0

许多热门服务都使用 OAuth 进行身份验证。OAuth 有多种类型和版本。

在 HTTP 基本身份验证中,用户只有一个用户名和密码,而 OAuth 允许使用特定于第三方应用的凭据向第三方应用授予对用户账号和数据的访问权限。此外,访问权限的范围也因应用而异。

如需了解 OAuth 1.0 的背景信息,请参阅 OAuth 核心指南。 具体而言,请参阅 6. 使用 OAuth 进行身份验证。在完整的三足式 OAuth 1.0 中,流程如下:

  1. 应用(“使用方”)获取请求令牌。
  2. 用户授权请求令牌。
  3. 应用使用请求令牌换取访问令牌。
  4. 对于所有后续资源请求,访问令牌会在签名请求中使用。

对于在没有用户互动的情况下使用 OAuth 1.0 的第三方服务(例如 Google Ads 脚本所需的服务),第 1、2 和 3 步无法实现。因此,某些服务会从其配置控制台颁发访问令牌,从而允许应用直接进入第 4 步。这称为单腿 OAuth 1.0。

OAuth1

Google Ads 脚本中的 OAuth 1.0

对于 Google Ads 脚本,每个脚本通常会被解读为一个应用。通过服务的控制台或管理设置页面,通常需要执行以下操作:

  • 设置应用配置,以表示脚本。
  • 指定要向脚本授予哪些权限。
  • 获取使用方密钥、使用方密钥、访问令牌和访问密钥,以便与单段式 OAuth 搭配使用。

OAuth 2.0

OAuth 2.0 用于在热门 API 中提供对用户数据的访问权限。给定第三方服务的账号所有者向特定应用授予权限,以允许这些应用访问用户数据。其优势在于,所有者:

  • 无需与应用共享其账号凭证。
  • 可以单独控制哪些应用有权访问数据,以及访问权限的范围。(例如,授予的访问权限可能是只读权限,或者仅限访问部分数据。)

如需在 Google Ads 脚本中使用启用了 OAuth 2.0 的服务,请执行以下几个步骤:

在脚本之外

授权 Google Ads 脚本通过第三方 API 访问您的用户数据。在大多数情况下,这涉及在第三方服务的控制台中设置应用。此应用代表您的脚本。

您需要指定应向 Google Ads 脚本应用授予哪些访问权限,并且通常会为其分配一个客户端 ID。这样,您就可以通过 OAuth 2.0 控制哪些应用可以访问您在第三方服务中的数据,以及它们可以查看或修改这些数据的哪些方面。

在脚本中

向远程服务器授权。根据服务器允许的授权类型,需要遵循一组不同的步骤(称为流程),但最终都会颁发访问令牌,该令牌将用于该会话的所有后续请求。

发出 API 请求。在每个请求中传递访问令牌。

授权流程

每种授权类型和相应的流程都适用于不同的使用场景。例如,当用户参与交互式会话时,与应用需要在没有用户的情况下在后台运行的场景相比,会使用不同的流程。

API 提供商将决定接受哪些授权类型,这将指导用户如何继续集成其 API。

实现

对于所有不同的 OAuth 流程,其目的都是获取访问令牌,然后该令牌可用于在会话的其余部分对请求进行身份验证。

示例库,说明了如何针对每种不同的流程类型进行身份验证。这些方法中的每一个都会返回一个对象,该对象会获取并存储访问令牌,并协助发出经过身份验证的请求。

一般使用模式如下:

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

客户端凭证授权

[客户端凭证授权][client-credentials-rfc] 是 OAuth2 流程的一种较简单形式,其中应用会交换应用独有的 ID 和密钥,以换取系统签发限时访问令牌。

客户端凭证

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

刷新令牌授权

刷新令牌授权与客户端凭证授权类似,对服务器的请求将返回可在会话中使用的访问令牌。

刷新令牌

获取刷新令牌

与刷新令牌授权的区别在于,虽然客户端凭证授权所需的详细信息来自应用配置(例如,在服务的控制面板中),但刷新令牌是作为更复杂的流程(例如 [授权代码授权][authorization-code-rfc])的一部分授予的,这需要用户互动:

授权代码

使用 OAuth Playground 获取刷新令牌

OAuth2 Playground 提供了一个界面,用户可以通过该界面逐步完成授权代码授权,以获取刷新令牌。

通过右上角的设置按钮,您可以定义要在 OAuth 流程中使用的所有参数,包括:

  • 授权端点:用作授权流程的起点。
  • 令牌端点:与刷新令牌搭配使用,用于获取访问令牌。
  • 客户端 ID 和密钥:应用的凭证。

    OAuth Playground

刷新令牌用量

完成初始授权后,服务可以签发刷新令牌,然后可以采用与客户端凭证流程类似的方式使用该令牌:

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

Search Ads 360 示例

Search Ads 360 就是一个可与刷新令牌搭配使用的 API。在此示例中,脚本会生成并返回报告。如需详细了解可以执行的其他操作,请参阅 Search Ads 360 API 参考文档。

创建脚本
  1. 在 Google Cloud 控制台中创建一个新项目,然后按照 Search Ads 360 指南中的步骤获取客户端 ID、客户端密钥和刷新令牌,并确保启用 Search Ads 360 API。
  2. 将 [示例脚本][search-ads-360-example] 粘贴到 Google Ads 中的新脚本中。
  3. 将 [OAuth2 库示例][oauth20-library-example] 粘贴到代码清单下方。
  4. 修改脚本,使其包含正确的客户端 ID、客户端密钥和刷新令牌值。

Apps 脚本 Execution API 示例

此示例演示了如何使用 Apps Script Execution API 在 Apps 脚本中执行函数。这样,您就可以从 Google Ads 脚本中调用 Apps 脚本。

创建 Apps 脚本

创建新脚本。以下示例将列出云端硬盘中的 10 个文件:

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
配置 Apps 脚本以供执行
  1. 保存脚本。
  2. 依次点击资源 > Cloud Platform 项目。
  3. 点击项目名称,前往 Google Cloud 控制台。
  4. 前往 API 和服务。
  5. 启用适当的 API,在本例中为 Drive API 和 Apps Script Execution API。
  6. 从菜单中的凭据项创建 OAuth 凭据。
  7. 返回脚本,通过发布 > 部署为可执行的 API 发布脚本以供执行。
创建 Google Ads 脚本
  1. 将示例脚本粘贴到 Google Ads 中的新脚本中。
  2. 此外,请将 [OAuth2 库示例][oauth20-library-example]粘贴到代码清单下方。
  3. 修改脚本,使其包含正确的客户端 ID、客户端密钥和刷新令牌值。

服务账号

授权类型的替代方案是服务账号的概念。

服务账号与授权类型的不同之处在于,服务账号不用于访问用户数据:身份验证后,请求由服务账号代表应用发出,而不是由可能拥有该项目的用户发出。例如,如果服务账号使用 Drive API 创建文件,则该文件将属于服务账号,并且默认情况下,项目所有者无法访问该文件。

Google Natural Language API 示例

[Natural Language API][natural-language-api-docs] 为文本提供 [情感分析][sentiment-analysis-api-docs] 和 [实体分析][entity-analysis-api-docs]。

此示例说明了如何计算广告文字(包括标题或广告内容描述)的 [情感][sentiment-api-docs]。这可以衡量 消息的积极程度和消息的影响力: 我们卖蛋糕和我们卖伦敦最好的蛋糕,哪个更好?立即购买!

设置脚本
  1. 在 Google Cloud 控制台中创建一个新项目。
  2. 启用 [Natural Language API][natural-language-api]。
  3. 为项目启用结算功能。
  4. [创建服务账号][create-service-account]。下载凭据 JSON 文件。
  5. 将 [示例脚本][natural-language-example] 粘贴到 Google Ads 中的新脚本中。
  6. 此外,请将 [OAuth2 库示例][oauth20-library-example]粘贴到代码清单下方。
  7. 替换必要的值:
    • serviceAccount:服务账号的邮箱,例如 xxxxx@yyyy.iam.gserviceaccount.com。
    • key:创建服务账号时下载的 JSON 文件中的密钥。开始时间:-----BEGIN PRIVATE KEY...,结束时间:...END PRIVATE KEY-----\n。

API 响应

API 可以返回各种格式的数据。其中最值得注意的是 XML 和 JSON。

JSON

作为响应格式,JSON 通常比 XML 更易于使用。不过,仍可能会出现一些问题。

回复验证

在成功调用 API 并获得响应后,下一步通常是使用 JSON.parse 将 JSON 字符串转换为 JavaScript 对象。此时,最好处理解析失败的情况:

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

此外,如果 API 不受您控制,请考虑响应的结构可能会发生变化,并且属性可能不再存在:

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

XmlService 允许您的脚本解析 XML 响应正文并从中提取数据。

验证

XML 仍然是构建 API 的常用格式。可以使用 XmlService parse 方法解析 API 调用的响应:

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

虽然 XmlService.parse 会检测 XML 中的错误并相应地抛出异常,但它不提供根据架构验证 XML 的功能。

根元素

成功解析 XML 文档后,使用 getRootElement() 方法获取根元素:

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

命名空间

在以下示例中,Sportradar API 用于获取所选比赛的足球比赛结果。XML 响应采用以下格式:

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

请注意命名空间在根元素中的指定方式。因此,您需要:

  • 从文档中提取命名空间属性。
  • 在遍历和访问子元素时,请使用此命名空间。

以下示例展示了如何访问 <schedule> 元素并在前面的文档代码段中搜索其 <sport_event> 子元素:

const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);

获取值

以下面的足球赛程为例:

<sport_event_status status="..." ... />

可以检索属性,例如:

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

可以使用 getText() 读取元素中包含的文本,但如果一个元素有多个文本子元素,这些子元素将被串联起来。如果可能存在多个文本子级,请考虑使用 getChildren() 并遍历每个子级。

Sportradar 示例

这个完整的 Sportradar 示例展示了如何检索足球比赛(特别是英格兰超级联赛)的详细信息。Soccer API 是 Sportradar 提供的众多体育赛事 Feed 之一。

设置 Sportradar 账号
  1. 前往 Sportradar 开发者网站
  2. 注册试用账号。
  3. 注册后,登录您的账号。
  4. 登录后,前往我的账号。

Sportradar 将不同的体育项目分到不同的 API 中。例如,您可能购买了 Soccer API 的访问权限,但没有购买 Tennis API 的访问权限。您创建的每个应用都可以关联不同的运动项目和不同的密钥。

  1. 在“应用”下,点击创建新应用。为应用提供名称和说明,并忽略网站字段。
  2. 仅选择为 Soccer Trial Europe v2 颁发新密钥。
  3. 点击注册应用。

成功后,您应该会看到一个包含新 API 密钥的页面。

  1. 将示例脚本粘贴到 Google Ads 中的新脚本中。
  2. 将清单中的 API 密钥替换为新颁发的密钥,然后修改邮箱字段。

问题排查

使用第三方 API 时,可能会因多种原因而发生错误,例如:

  • 客户端向服务器发出请求时,未采用 API 预期的格式。
  • 客户端预期的响应格式与遇到的响应格式不同。
  • 客户端使用无效的令牌或密钥,或使用占位符值。
  • 客户端达到用量限额。
  • 客户端提供了无效参数。

在所有这些情况以及其他情况下,确定问题原因的第一步是检查导致错误的响应的详细信息。

解析回答

默认情况下,Google Ads 脚本引擎会抛出任何返回错误(状态代码为 400 或更高)的响应。

为防止此行为并允许检查错误和出错提示,请将可选参数的 muteHttpExceptions 属性设置为 UrlFetchApp.fetch。例如:

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

常见状态代码

  • 200 OK 表示成功。如果回答不包含预期数据,请考虑以下事项:

    • 某些 API 允许指定要使用的字段和/或响应格式。如需了解详情,请参阅 API 文档。
    • 一个 API 可能有多个可调用的资源。请参阅文档,确定是否有其他资源更适合使用,并且会返回您所需的数据。
    • 自代码编写以来,API 可能已发生变化。请参阅文档或咨询开发者以获取说明。
  • 400 Bad Request 通常表示发送到服务器的请求的格式或结构不正确。检查请求并将其与 API 规范进行比较,以确保其符合预期。如需详细了解如何检查请求,请参阅检查请求。

  • 401 Unauthorized 通常表示在调用 API 时未提供或未成功执行授权。

    • 如果 API 使用基本授权,请确保在请求中构建并提供 Authorization 标头。
    • 如果 API 使用 OAuth 2.0,请确保已获取访问令牌,并将其作为不记名令牌提供。
    • 对于任何其他授权变体,请确保提供请求所需的凭据。
  • 403 Forbidden 表示用户无权访问所请求的资源。

    • 确保用户已被授予必要的权限,例如,在基于文件的请求中向用户授予对文件的访问权限。
  • 404 Not Found 表示请求的资源不存在。

    • 检查用于 API 端点的网址是否正确。
    • 如果提取资源,请检查所引用的资源是否存在(例如,对于基于文件的 API,文件是否存在)。

检查请求

当 API 响应指示请求格式不正确(例如 400 状态代码)时,检查请求非常有用。为了帮助检查请求,UrlFetchApp 提供了 fetch() 方法的配套方法,称为 getRequest(url, params)

此方法不会向服务器发送请求,而是构建本应发送的请求,然后将其返回。这样,用户就可以检查请求的元素,以确保请求看起来正确。

例如,如果请求中的表单数据由许多串联在一起的字符串组成,则错误可能出在您为生成该表单数据而创建的函数中。最简单的情况:

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

让您能够检查请求的元素。

记录请求和响应

为了协助检查对第三方 API 的请求和响应的整个过程,可以使用以下辅助函数作为 UrlFetchApp.fetch() 的直接替代项,以同时记录请求和响应。

  1. 将代码中出现的所有 UrlFetchApp.fetch() 替换为 logUrlFetch()。

  2. 将以下函数添加到脚本末尾。

    function logUrlFetch(url, opt_params) {
     const params = opt_params || {};
     params.muteHttpExceptions = true;
     const request = UrlFetchApp.getRequest(url, params);
     console.log('Request:       >>> ' + JSON.stringify(request));
     const response = UrlFetchApp.fetch(url, params);
     console.log('Response Code: <<< ' + response.getResponseCode());
     console.log('Response text: <<< ' + response.getContentText());
     if (response.getResponseCode() >= 400) {
       throw Error('Error in response: ' + response);
     }
     return response;
    }
    

执行脚本时,所有请求和响应的详细信息都会记录到控制台,以便于调试。

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities