מעבר מ-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 (בטא).

למידה

לשיטות השירות הרגילות של 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. לפרטים נוספים, ראו אימות.

אם אתם משתמשים בספריית לקוח, אתם יכולים להגדיר את Application Default Credentials (פרטי כניסה שמוגדרים כברירת מחדל לאפליקציה) על ידי הגדרת משתנה הסביבה 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.

    Ad Manager SOAP API PQL

    // 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 (בטא). אם רוצים לציין סדר מיון לסט התוצאות, מסירים את פסוקית PQL‏ ORDER BY ומגדירים במקום זאת את השדה orderBy:

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

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

‫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

העברת דוחות

אפשר להשתמש ב-SOAP API רק כדי לקרוא דוחות ולהריץ אותם בכלי הדוחות שהוצא משימוש. לעומת זאת, ה-REST API יכול רק לקרוא, לכתוב ולהריץ דוחות אינטראקטיביים.

לכלי הדיווח ולממשקי ה-API יש מרחב מזהים שונה. אי אפשר להשתמש במזהה של SavedQuery ב-SOAP API ב-REST API.

אם אתם משתמשים ב-SavedQuery, אתם יכולים להעביר את הדוח לדוח אינטראקטיבי בממשק המשתמש וליצור מיפוי בין שני מרחבי המזהים. מידע נוסף על העברת דוחות זמין במאמר בנושא העברת דוחות לדוחות אינטראקטיביים.

הסבר על ההבדלים בין ממשקי API

יש כמה הבדלים בין האופן שבו SOAP API ו-REST API מטפלים בהגדרות ובתוצאות של דוחות:

  • ב-SOAP API, אם בדוח נדרש רק NAME, המערכת מוסיפה אוטומטית מאפיין ID תואם לתוצאות. ב-REST API, צריך להוסיף באופן מפורש את המאפיין ID אל ReportDefinition כדי שהוא ייכלל בתוצאות.

  • ל-SOAP API לא היו סוגים מפורשים למדדים. ב-API ל-REST מוגדר סוג נתונים, שמתועד בערך enum‏ Dimension. חשוב לדעת שמאפייני ENUM הם סוגי enum פתוחים. כשמנתחים את התוצאות, צריך לטפל בערכי enum חדשים ולא מוכרים.

  • הפרדנו את Dimensions ו-DimensionAttributes ב-SOAP API. ל-REST API יש enum מאוחד Dimension שמכיל את שניהם.

  • ב-SOAP API לא הייתה הגבלה על מספר המימדים. בדוחות אינטראקטיביים יש מגבלה של 10 מאפיינים גם בממשק המשתמש וגם ב-API. מאפיינים שמתבססים על אותו מרחב מזהים נספרים כמאפיין אחד. לדוגמה, אם כוללים רק את ORDER_NAME, את ORDER_ID ואת ORDER_START_DATE, זה נחשב לממד אחד בחישוב המגבלה.