迁移到 Postmaster Tools API v2

本指南介绍了 Postmaster Tools API 的 v1 和 v2 之间的区别，以及如何将 v1 应用迁移到 v2。

概览

Postmaster Tools API 第 2 版引入了多项新功能，并整合了用于检索电子邮件统计信息的现有功能。借助 v2，您现在可以：

  • 检索指定日期范围内的统计数据，而不是每天的统计数据。
  • 查询发件人政策框架 (SPF)、域名密钥识别邮件 (DKIM) 和基于网域的邮件身份验证、报告和一致性协议 (DMARC) 的合规性状态。
  • 通过一次 API 调用检索多个网域的统计信息。

主要变更包括：

  • trafficStats 资源已替换为 domainStats。
  • domains.trafficStats.get 和 domains.trafficStats.list 方法已替换为单个 domains.domainStats.query 方法。
  • 现在可以使用新的 domains.getComplianceStatus 方法来检索指定网域的 SPF、DKIM 和 DMARC 合规性状态。
  • 新增了 domainStats.batchQuery 方法，可通过一次调用检索多个网域的统计信息。
  • v1 中使用的“指标”一词已重命名为“统计数据”。

更新到 v2

如需从 v1 迁移到 v2，您需要将客户端库更新到最新版本，并修改代码以使用 v2 资源和方法。

  1. 将您的 Postmaster Tools API 客户端库更新到版本 2 或更高版本。
  2. 将所有从 trafficStats 资源到 domainStats 资源的调用都进行了更改。
  3. 将对 domains.trafficStats.get 或 domains.trafficStats.list 的所有调用替换为 domains.domainStats.query，并提供 startDate 和 endDate 参数来指定查询的日期范围。

检索电子邮件统计信息

在 v1 中，电子邮件指标是使用 domains.trafficStats.get（针对单天）或 domains.trafficStats.list（针对多天）检索的。在 v2 中，电子邮件统计信息使用 domains.domainStats.query 进行检索。

通过指定 startDate 和 endDate，您可以使用 domains.domainStats.query 方法检索指定日期范围内的统计信息。

v1：domains.trafficStats.get

Java

String query = String.format("domains/%s/trafficStats/%s", domainName, date);
TrafficStats trafficStats = service.domains().trafficStats().get(query).execute();

Python

query = 'domains/%s/trafficStats/%s' %(domain_name,date)
traffic_stats = service.domains().trafficStats().get(name=query).execute();

v2：domains.domainStats.query（单日）

如需在 v2 中检索单日统计信息，请使用相同的 startDate 和 endDate 调用 domains.domainStats.query。

Java

Date date = new Date().setYear(2024).setMonth(1).setDay(1);
QueryDomainStatsResponse statsResponse = service.domains().domainStats()
        .query("domains/" + domainName)
        .setStartDate(date)
        .setEndDate(date)
        .execute();

Python

date = {'year': 2024, 'month': 1, 'day': 1}
stats = service.domains().domainStats().query(
    parent='domains/' + domain_name,
    startDate=date,
    endDate=date).execute()

v1：domains.trafficStats.list

Java

ListTrafficStatsResponse listTrafficStatsResponse = service.domains().trafficStats().list("domains/" + domainName)
        .execute();

Python

query = 'domains/' + domain_name
list_traffic_stats_response = service.domains().trafficStats().list(parent=query).execute();

v2：针对日期范围的 domains.domainStats.query

如需在 v2 中检索某个日期范围内的统计信息，请使用 startDate 和 endDate 调用 domains.domainStats.query。

Java

Date startDate = new Date().setYear(2024).setMonth(1).setDay(1);
Date endDate = new Date().setYear(2024).setMonth(1).setDay(7);
QueryDomainStatsResponse statsResponse = service.domains().domainStats()
        .query("domains/" + domainName)
        .setStartDate(startDate)
        .setEndDate(endDate)
        .execute();

Python

stats = service.domains().domainStats().query(
    parent='domains/' + domain_name,
    startDate={'year': 2024, 'month': 1, 'day': 1},
    endDate={'year': 2024, 'month': 1, 'day': 7}).execute()

新版 v2 功能

除了将 get 和 list 流量统计信息整合到 query 中之外，v2 还引入了以下功能。

检索合规性状态

您可以使用 domains.getComplianceStatus 检索网域的发件人政策框架 (SPF)、域名密钥识别邮件 (DKIM) 和基于网域的邮件身份验证、报告和一致性 (DMARC) 的合规性状态。

如需查看示例代码，请参阅检索电子邮件统计信息。

批量查询网域统计信息

您可以使用 domainStats.batchQuery 通过一次调用检索多个网域的统计信息。