遷移至 Postmaster Tools API v2

本指南說明 Postmaster Tools API 第 1 版和第 2 版的差異，以及如何將第 1 版應用程式遷移至第 2 版。

總覽

Postmaster Tools API 第 2 版推出多項新功能，並整合現有功能，方便您擷取電子郵件統計資料。現在，您可以使用第 2 版執行下列操作：

  • 擷取指定日期範圍的統計資料，而非每日資料。
  • 查詢寄件者政策架構 (SPF)、網域金鑰認證郵件 (DKIM) 和網域型郵件驗證、報告與一致性 (DMARC) 的相容性狀態。
  • 透過單一 API 呼叫，擷取多個網域的統計資料。

主要異動包括：

  • trafficStats 資源已替換為 domainStats。
  • domains.trafficStats.get 和 domains.trafficStats.list 方法已由單一 domains.domainStats.query 方法取代。
  • 我們提供新的 domains.getComplianceStatus 方法，可擷取特定網域的 SPF、DKIM 和 DMARC 相容性狀態。
  • 現在可以使用新的 domainStats.batchQuery 方法，在單一呼叫中擷取多個網域的統計資料。
  • 第 1 版中使用的「指標」一詞已重新命名為「統計資料」。

更新至第 2 版

如要從第 1 版遷移至第 2 版，請將用戶端程式庫更新至最新版本，並修改程式碼以使用第 2 版的資源和方法。

  1. 將 Postmaster Tools API 用戶端程式庫更新至 2 以上版本。
  2. 將所有來自 trafficStats 資源的呼叫變更為 domainStats 資源。
  3. 將所有對 domains.trafficStats.get 或 domains.trafficStats.list 的呼叫替換為 domains.domainStats.query，並提供 startDate 和 endDate 參數，指定查詢的日期範圍。

擷取電子郵件統計資料

在第 1 版中，電子郵件指標是使用 domains.trafficStats.get 擷取單日資料，或使用 domains.trafficStats.list 擷取多日資料。在第 2 版中，電子郵件統計資料是使用 domains.domainStats.query 擷取。

domains.domainStats.query 方法可讓您指定 startDate 和 endDate，擷取特定日期範圍的統計資料。

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 (單日)

如要在第 2 版中擷取單日統計資料，請使用相同的 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 指定日期範圍

如要在第 2 版中擷取特定日期範圍的統計資料，請使用 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，透過單一呼叫擷取多個網域的統計資料。