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 les protocoles SPF (Sender Policy Framework), DKIM (DomainKeys Identified Mail) et DMARC (authentification DMARC) ;
  • 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é des protocoles 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é des protocoles SPF (Sender Policy Framework), DKIM (DomainKeys Identified Mail) et DMARC (Domain-based Message Authentication, Reporting and Conformance) pour un domaine à l'aide de domains.getComplianceStatus.

Consultez Récupérer les statistiques sur les e-mails pour obtenir un exemple de code.

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.