מעבר מ-Ad Manager SOAP API

Ad Manager SOAP API הוא ממשק API מדור קודם לקריאה ולכתיבה של נתוני Ad Manager ולהרצת דוחות. אם יש לכם אפשרות להעביר את הנתונים, מומלץ להשתמש ב-Ad Manager API (בטא). עם זאת, יש תמיכה בגרסאות של Ad Manager SOAP API במהלך מחזור החיים הרגיל שלהן. מידע נוסף זמין בלוח הזמנים להוצאה משימוש של Ad Manager SOAP API.

במדריך הבא מפורטים ההבדלים בין Ad Manager SOAP API לבין Ad Manager API (בטא).

למידה

ל-methods הרגילים של שירות Ad Manager SOAP API יש מושגים מקבילים ב-Ad Manager API. ב-Ad Manager API יש גם שיטות לקריאת ישויות בודדות. בטבלה הבאה מוצגת דוגמה למיפוי של שיטות Order:

שיטת SOAP שיטות REST
getOrdersByStatement networks.orders.get
networks.orders.list

אמת

כדי לבצע אימות באמצעות Ad Manager API (בטא), אפשר להשתמש בפרטי הכניסה הקיימים ל-Ad Manager SOAP API או ליצור פרטי כניסה חדשים. בכל אחת מהאפשרויות, קודם צריך להפעיל את Ad Manager API בפרויקט ב-Google Cloud. פרטים נוספים זמינים במאמר אימות.

אם אתם משתמשים בספריית לקוח, מגדירים את פרטי הכניסה שמוגדרים כברירת מחדל לאפליקציה על ידי הגדרת משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS לנתיב של קובץ המפתח של חשבון השירות. פרטים נוספים זמינים במאמר הסבר על Application Default Credentials.

אם אתם משתמשים בפרטי כניסה של אפליקציה מותקנת, צריך ליצור קובץ JSON בפורמט הבא ולהגדיר את משתנה הסביבה לנתיב שלו במקום זאת:

{
  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "refresh_token": "REFRESH_TOKEN",
  "type": "authorized_user"
}

מחליפים את הערכים הבאים:

  • CLIENT_ID: מזהה הלקוח החדש או הקיים.
  • CLIENT_SECRET: הסוד החדש או הקיים של הלקוח.

  • REFRESH_TOKEN: אסימון הרענון החדש או הקיים.

Linux או macOS 

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows 

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

הסבר על ההבדלים בין מסננים

שפת השאילתות של Ad Manager API (בטא) תומכת בכל התכונות של שפת השאילתות של בעלי תוכן דיגיטלי (PQL), אבל יש הבדלים משמעותיים בתחביר.

הדוגמה הבאה להצגת רשימה של אובייקטים מסוג Order ממחישה את השינויים העיקריים, כמו הסרת משתני קישור, אופרטורים תלויי-אותיות רישיות והחלפת התנאים ORDER BY ו-LIMIT בשדות נפרדים:

Ad Manager SOAP API 

<filterStatement>
  <query>WHERE name like "PG_%" and lastModifiedDateTime &gt;= :lastModifiedDateTime ORDER BY id ASC LIMIT 500</query>
  <values>
    <key>lastModifiedDateTime</key>
    <value xmlns:ns2="https://www.google.com/apis/ads/publisher/v202502" xsi:type="ns2:DateTimeValue">
      <value>
        <date>
          <year>2024</year>
          <month>1</month>
          <day>1</day>
        </date>
        <hour>0</hour>
        <minute>0</minute>
        <second>0</second>
        <timeZoneId>America/New_York</timeZoneId>
      </value>
    </value>
  </values>
</filterStatement>

Ad Manager API (בטא)

פורמט JSON

{
  "filter": "displayName = \"PG_*\" AND updateTime > \"2024-01-01T00:00:00-5:00\"",
  "pageSize": 500,
  "orderBy":  "name"
}

כתובת URL מקודדת

GET https://admanager.googleapis.com/v1/networks/123/orders?filter=displayName+%3D+\"PG_*\"+AND+updateTime+%3E+\"2024-01-01T00%3A00%3A00-5%3A00\"

Ad Manager API (בטא) תומך בכל היכולות של PQL, עם ההבדלים הבאים בסינטקס בהשוואה ל-Ad Manager SOAP API:

  • האופרטורים AND ו-OR תלויי אותיות רישיות ב-Ad Manager API (בטא). and ו-or באותיות קטנות נחשבים כמחרוזות חיפוש מילוליות ריקות, תכונה ב-Ad Manager API (בטא) שמאפשרת לחפש בשדות שונים.

    שימוש באופרטורים באותיות רישיות

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'.
notes = "lorem ipsum" AND archived = false

    אותיות קטנות נחשבות כמילת מפתח

    // Matches unarchived Orders where order.notes has the value 'lorem ipsum'
// and any field in the order has the literal value 'and'.
notes = "lorem ipsum" and archived = false

  • התו * הוא תו כללי לחיפוש להתאמה למחרוזת. ב-Ad Manager API (בטא) אין תמיכה באופרטור like.

    PQL של Ad Manager SOAP API

    // Matches orders where displayName starts with the string 'PG_'
displayName like "PG_%"

    Ad Manager API (בטא)

    // Matches orders where displayName starts with the string 'PG_'
displayName = "PG_*"

  • שמות השדות חייבים להופיע בצד ימין של אופרטור ההשוואה:

    מסנן תקין

    updateTime > "2024-01-01T00:00:00Z"

    מסנן לא חוקי

    "2024-01-01T00:00:00Z" < updateTime

  • ב-Ad Manager API (בטא) אין תמיכה במשתני קישור. כל הערכים חייבים להיות מוטמעים.

  • מחרוזות לוגיות שמכילות רווחים חייבות להיות מוקפות במירכאות כפולות, לדוגמה "Foo bar". אי אפשר להשתמש בגרשיים בודדים כדי לעטוף מחרוזות לוגיות.

הסרת תנאי סדר

אפשר לציין סדר מיון אופציונלי ב-Ad Manager API (בטא). אם רוצים לציין סדר מיון של קבוצת התוצאות, מסירים את התנאי ORDER BY ב-PQL ומגדירים את השדה orderBy במקום זאת:

GET networks/${NETWORK_CODE}/orders?orderBy=updateTime+desc

מעבר מ-offsets לאסימונים של חלוקה לדפים

ב-Ad Manager API (בטא) נעשה שימוש באסימונים של חלוקה לדפים במקום בתנאי LIMIT ו-OFFSET כדי לעבור בין דפי קבוצות תוצאות גדולות.

ב-Ad Manager API (בטא) נעשה שימוש בפרמטר pageSize כדי לשלוט בגודל הדף. בניגוד לפסקה LIMIT ב-Ad Manager SOAP API, השמטה של גודל דף לא מחזירה את כל קבוצת התוצאות. במקום זאת, שיטת הרשימה משתמשת בגודל דף ברירת מחדל של 50. בדוגמה הבאה, הערכים pageSize ו-pageToken מוגדרים כפרמטרים של כתובת ה-URL:

# Initial request
GET networks/${NETWORK_CODE}/orders?pageSize=50

# Next page
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

בניגוד ל-Ad Manager SOAP API, יכול להיות ש-Ad Manager API (בטא) יחזיר פחות תוצאות מגודל הדף המבוקש, גם אם יש דפים נוספים. משתמשים בשדה nextPageToken כדי לבדוק אם יש תוצאות נוספות.

אמנם לא נדרש שינוי אופקי כדי לפצל את הדפים, אבל אפשר להשתמש בשדה skip ליצירת מספר תהליכים. כשמשתמשים בכמה שרשורים, צריך להשתמש באסימון העימוד מהדף הראשון כדי לוודא שקוראים מאותה קבוצת תוצאות:

# First thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}

# Second thread
GET networks/${NETWORK_CODE}/orders?pageSize=50&pageToken=${TOKEN_FROM_INITIAL_REQUEST}&skip=50