מעבר ל-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();

גרסה 2: 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 כוללת את התכונות הבאות.

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

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

דוגמאות קוד מופיעות במאמר בנושא אחזור נתונים סטטיסטיים של אימייל.

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

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