ניהול גרסאות סמנטי
Google Ads API פועל לפי ניהול גרסאות סמנטי עם מספר גרסה ראשית ומשנית. הגרסאות נכתבות כ-MAJOR.MINOR או כ-vMAJOR.MINOR.
לדוגמה, v25.0 (או v25) היא גרסה ראשית, ואילו v25.1 היא גרסה משנית.
פרטים על הגרסאות הנוכחיות והקודמות מופיעים בהערות המוצר.
גרסאות ראשיות
גרסאות ראשיות כוללות שינויים שעלולים לשבור את התאימות לאחור. הגרסה הראשונית של גרסה ראשית מסתיימת באפס (vX.0 או vX, כאשר X הוא מספר הגרסה הראשית).
לכל גרסה ראשית יש נתיב נפרד לנקודת קצה של REST ו-gRPC (vX), שלא כולל את הסיומת של הגרסה המשנית. בכתובת ה-URL הבאה, X הוא מספר הגרסה הראשית (לדוגמה, v25):
https://googleads.googleapis.com/vX
אם אתם משדרגים מגרסה ראשית ישנה יותר, יכול להיות שתצטרכו לבצע שינויים בקוד כשאתם עוברים לנקודת הקצה של הגרסה הראשית החדשה. אם אתם משתמשים בספריות הלקוח שלנו, אתם צריכים לשדרג לגרסת ספריית הלקוח שתומכת בגרסה הראשית החדשה. כשגרסה ראשית חדשה יוצאת, אנחנו מספקים מדריך לשדרוג שיעזור לכם לפתור שינויים שעלולים לשבור את הקוד.
דוגמאות לשינויים שעלולים לשבור את התאימות:
- הסרה או שינוי שם של שירות, ממשק, שדה, שיטה או ערך enum.
- שינוי הסוג של שדה.
- שינוי הפורמט של שם המשאב.
- שינוי הפורמט של כתובת ה-URL בהגדרה של HTTP.
- שינוי פורמטים של פלט, כמו שינוי ערכי ברירת מחדל.
- שינוי סיבת השגיאה שהוחזרה מ-A ל-B.
גרסאות משניות
בגרסאות משניות מוצגים רק שינויים שתואמים לגרסאות קודמות. בגרסה משנית, המספר vMAJOR.MINOR MINOR גדול מאפס (לדוגמה, v25.1).
כשגרסת משנה יוצאת, נקודת הקצה הקיימת של הגרסה הראשית (https://googleads.googleapis.com/vX) מתעדכנת אוטומטית במקום. אין צורך לשנות את נתיב הגרסה בכתובות ה-URL של נקודות הקצה, והקוד הקיים ימשיך לפעול בלי שיבושים.
בגרסאות משניות מתווספות תכונות או עדכונים שלא משפיעים על הקוד הקיים. כדי להשתמש בשדות או בתכונות מגרסה משנית עם ספריית לקוח, צריך לשדרג את ספריית הלקוח לגרסה שכוללת את ההגדרות של הגרסה המשנית.
הוצאה משימוש והפסקת תמיכה
מדי פעם, גרסאות ישנות יותר של Google Ads API מוצאות משימוש ולאחר מכן יוצאות מכלל פעולה:
- הוצאה משימוש: כשגרסה ראשית (כמו
v25) יוצאת, כל הגרסאות הראשיות הקודמות מסומנות כגרסאות שהוצאו משימוש. קריאות ל-API לגרסאות שהוצאו משימוש ימשיכו לפעול עד לתאריך ההוצאה משימוש, וגרסאות קיימות של ספריות לקוח ימשיכו לתמוך בהן, אבל גרסאות עתידיות של ספריות לקוח לא יכללו גרסאות API שהוצאו משימוש כדי להקטין את גודל החבילה. - הוצאה משימוש: גרסה מושבתת בתאריך ההוצאה משימוש שלה, וכל הקריאות ל-API לנקודת הקצה שלה נכשלות.
אנחנו מפרסמים הודעות בבלוג למפתחים לפני הוצאה משימוש של גרסאות. כדאי לעיין בלוח הזמנים להוצאה משימוש כדי לראות את התאריכים הפעילים, התאריכים שבהם הוצאו משימוש והתאריכים שבהם יצאו משימוש.