Migrer vers l'API Postmaster Tools v2

Ce guide décrit les différences entre la version 1 et la version 2 de l'API Postmaster Tools, et explique comment migrer votre application de la version 1 vers la version 2.

Présentation

La version 2 de l'API Postmaster Tools introduit plusieurs nouvelles fonctionnalités et consolide les fonctionnalités existantes pour récupérer les statistiques sur les e-mails. Avec la version 2, vous pouvez désormais :

  • récupérer des statistiques sur des plages de dates plutôt que par jour ;
  • interroger l'état de conformité pour SPF (Sender Policy Framework), DKIM (DomainKeys Identified Mail) et DMARC (Domain-based Message Authentication, Reporting, and Conformance) ;
  • récupérer des statistiques pour plusieurs domaines avec un seul appel d'API.

Principales modifications :

  • La ressource trafficStats a été remplacée par domainStats.
  • Les méthodes domains.trafficStats.get et domains.trafficStats.list ont été remplacées par une seule méthode domains.domainStats.query.
  • Une nouvelle méthode domains.getComplianceStatus est disponible pour récupérer l'état de conformité pour SPF, DKIM et DMARC pour un domaine donné.
  • Une nouvelle méthode domainStats.batchQuery est disponible pour récupérer les statistiques de plusieurs domaines en un seul appel.
  • Le terme "métriques" utilisé dans la version 1 a été renommé "statistiques".

Passer à la version 2

Pour migrer de la version 1 vers la version 2, vous devez mettre à jour votre bibliothèque cliente vers la dernière version et modifier votre code pour utiliser les ressources et les méthodes de la version 2.

  1. Mettez à jour votre bibliothèque cliente de l'API Postmaster Tools vers la version 2 ou une version ultérieure.
  2. Remplacez tous les appels de la ressource trafficStats par la ressource domainStats.
  3. Remplacez tous les appels à domains.trafficStats.get ou domains.trafficStats.list par domains.domainStats.query, en fournissant les paramètres startDate et endDate pour spécifier la plage de dates de la requête.

Récupérer les statistiques sur les e-mails

Dans la version 1, les métriques sur les e-mails étaient récupérées à l'aide de domains.trafficStats.get pour un seul jour ou de domains.trafficStats.list pour plusieurs jours. Dans la version 2, les statistiques sur les e-mails sont récupérées à l'aide de domains.domainStats.query.

La méthode domains.domainStats.query vous permet de récupérer des statistiques sur une plage de dates en spécifiant startDate et endDate.

Version 1 : 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()

Version 2 : domains.domainStats.query pour un seul jour

Pour récupérer les statistiques d'un seul jour dans la version 2, appelez domains.domainStats.query avec les mêmes startDate et endDate.

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

Version 1 : 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()

Version 2 : domains.domainStats.query pour une plage de dates

Pour récupérer les statistiques d'une plage de dates dans la version 2, appelez domains.domainStats.query avec une startDate et une endDate.

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

Nouvelles fonctionnalités de la version 2

En plus de consolider les statistiques sur le trafic get et list dans query, la version 2 introduit les fonctionnalités suivantes.

Récupérer l'état de conformité

Vous pouvez récupérer l'état de conformité pour SPF, DKIM et DMARC pour un domaine à l'aide de domains.getComplianceStatus.

Pour obtenir un exemple de code, consultez Récupérer l'état de conformité d'un domaine.

Interroger par lot les statistiques sur les domaines

Vous pouvez récupérer les statistiques de plusieurs domaines en un seul appel à l'aide de domainStats.batchQuery.