מעבר ל-Postmaster Tools API v2

במדריך הזה מוסברים ההבדלים בין גרסה 1 לגרסה 2 של Postmaster Tools API, ואיך מעבירים אפליקציה מגרסה 1 לגרסה 2.

סקירה כללית

גרסה 2 של Postmaster Tools API כוללת כמה תכונות חדשות ומאחדת פונקציות קיימות לאחזור נתונים סטטיסטיים של אימייל. בגרסה 2, אפשר עכשיו:

  • אפשר לאחזר נתונים סטטיסטיים לפי טווחי תאריכים במקום לפי יום.
  • שאילתת סטטוס התאימות של Sender Policy Framework ‏ (SPF),‏ DomainKeys Identified Mail ‏ (DKIM) ופרוטוקול מבוסס-דומיין לאימות, דיווח והתאמה של הודעות (DMARC).
  • אפשר לאחזר נתונים סטטיסטיים של כמה דומיינים באמצעות קריאה אחת ל-API.

השינויים העיקריים כוללים:

  • המשאב trafficStats הוחלף ב-domainStats.
  • ה-methods‏ domains.trafficStats.get ו-domains.trafficStats.list הוחלפו ב-method‏ domains.domainStats.query יחיד.
  • יש שיטה חדשה domains.getComplianceStatus לאחזור סטטוס התאימות של SPF,‏ DKIM ו-DMARC לדומיין נתון.
  • יש method‏ 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, קוראים ל-domains.domainStats.query עם אותם startDate ו-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()

‫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, קוראים ל-domains.domainStats.query עם startDate ו-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()

תכונות חדשות בגרסה 2

בנוסף לאיחוד נתוני התנועה של get ו-list ב-query, גרסה 2 כוללת את התכונות הבאות.

אחזור סטטוס התאימות

אפשר לאחזר את סטטוס התאימות של SPF,‏ DKIM ו-DMARC לדומיין באמצעות domains.getComplianceStatus.

דוגמאות קוד זמינות במאמר איך מאחזרים את סטטוס התאימות של דומיין.

שאילתת נתונים סטטיסטיים של דומיין באצווה

אפשר לאחזר נתונים סטטיסטיים של כמה דומיינים באמצעות קריאה אחת באמצעות domainStats.batchQuery.