שיטות מומלצות

במאמר זה מפורטות שיטות מומלצות שונות שכדאי לשקול כשמפתחים אפליקציות מול Google Ad Manager API.

שימוש חוזר בלקוחות שירות/ב-stub במהלך הביצוע

ליצירה של לקוח שירות או stub חדשים יש עלות שולית שקשורה לאחזור ה-WSDL והקצאת משאבים. אם אפשר, כדאי ליצור את הלקוח/ה-stub של השירות פעם אחת בתחילת הביצוע, ולהפוך אותו לזמין למחלקות ולפונקציות לפי הצורך.

שימוש באפשרות הדפדוף בעת אחזור אובייקטים

כל השירותים תומכים בשיטת get*ByStatement(), שמאפשרת לסנן את התוצאות באמצעות תחביר PQL. ניתן להשתמש בסעיפים LIMIT ו-OFFSET כדי לפצל קבוצות גדולות של תוצאות לדפים, וכך למנוע פסקי זמן ולשמור על גודל סביר של דפי התגובות. גודל הדף המוצע הוא 200-500, בהתאם למורכבות האובייקטים.

בקשות לעדכון בכמות גדולה

כשמשנים מספר אובייקטים מאותו סוג, כדאי לשלוח את כל האובייקטים באותה בקשת update*(), וכך לשפר את הביצועים. לכל בקשה יש תקורה שולית על הלקוח ועל השרת, וקיבוץ בקשות יכול להיות אמצעי יעיל לצמצום מספר הבקשות. לדוגמה, תוכלו להשתמש ב-updateOrders כדי לעדכן קבוצה של Orders במקום הזמנה אחת בכל שיחה.

שימוש בפרמטרים של קישור ב-PQL

פרמטרים של קישור הם דרך להוסיף משתנים להצהרת שאילתה של PQL. PQL מתייחס למשתנה קישור בשם ללא רווחים שמתחיל בנקודתיים, למשל, :name. ניתן לראות דוגמה לקוד בדף תחביר PQL.

אנחנו ממליצים להשתמש במשתני קישור כי הם משפרים את קריאות הקוד כי הם מבטלים את הצורך לשרשר מחרוזות ומשתנים להצהרת שאילתה. הם גם מקלים על השימוש חוזר בהצהרות PQL, כי אפשר ליצור שאילתות חדשות על ידי החלפת ערכי הפרמטרים של הקישור (bind).

הענק הרשאות משתמש במידה מועטה

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

לא חורגים מהמכסות

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

מכסת API

המכסה הראשונה שמוחלת על בקשות API היא מכסה ברמת הרשת. בחשבונות Ad Manager 360 המגבלה היא 8 בקשות לשנייה, ובחשבונות Ad Manager המגבלה היא 2 בקשות לשנייה. חריגה מהמגבלה הזו תוביל לשגיאה QuotaError.EXCEEDED_QUOTA. כל בקשות ה-API שנשלחות ברשת שלכם חלות על המכסה הזו, כולל אפליקציות של צד שלישי שאתם או מישהו בחברה נתתם להן גישת API לרשת שלכם.

מכסות ספציפיות למערכת

מכסת ה-API לבדה לא מספיקה כדי להגן כראוי על מערכות מסוימות ב-Ad Manager שצורכות משאבים רבים. מערכות הדיווח והתחזית מגדירות מכסות משלהן שעלולות לגרום לשגיאות ב-API: QuotaError.REPORT_JOB_LIMIT ו- ForecastError.EXCEEDED_QUOTA, בהתאמה.

טיפול בשגיאות מכסות

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