סטנדרטים של פרוטוקול

ה-API פועל לפי סדרת תקנים של HTTP API אידמפוטנטיות כדי לאפשר בינה מלאכותית של Google Analytics.

כתובות URL שמתארחות ב-Google

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

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

אם מספר החשבון של מבצע הקריאה המשולבת הוא INTEGRATOR_1, עליו להוסיף שבסוף כתובת ה-URL כדי ליצור:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

כתובות URL שמתארחות אצל שותפים

מסמכי התיעוד לכל method של API שמתארח אצל שותף מספקים כתובת URL בסיסית, כולל את שם ה-method ואת מספר הגרסה הראשית. אין לכלול את מספר החשבון של הכלי לשילוב תשלומים (PIAID) בכתובות ה-URL שאתם מארחים.

סביבות Sandbox וייצור

Google מארחת ממשקי API רגילים של Payments גם ב-Sandbox (לפיתוח וגם למטרות בדיקה) ועל הייצור. בקשות בסביבת ה-Sandbox של Google לא מובילות לחבות פיננסית בעולם האמיתי. ארגז החול שסביבות הייצור הן נפרדות לחלוטין ולא חולקים מפתחות או מידע על העסקה.

Google מצפה שארגז החול שלך יהיה זמין באופן עקבי, כי נשתמש Sandbox כדי לבדוק קודם שינויים ותכונות חדשות.

נתיב הבסיס של ארגז החול של Google

https://vgw.sandbox.google.com/secure-serving/gsp/

הנתיב של Google בסביבת הייצור

https://vgw.googleapis.com/secure-serving/gsp/

במדריך הזה נשתמש בנקודות הקצה לסביבת הייצור.

סוג התוכן והקידוד

מטענים ייעודיים של הודעות שמשתמשים בהצפנת PGP חייבים להשתמש בסוג התוכן application/octet-stream; charset=utf-8. גופי בקשות PGP חייבים יישלחו בקידוד base64url, כפי שמוגדר rfc4648 §5. מטענים ייעודיים של הודעות שמשתמשים בהצפנת JWE חייבים להשתמש בסוג התוכן application/jose; charset=utf-8. האפשרות 'עריכה טורית קומפקטית' שנתמך על ידי JWE/JWS מטפל בקידוד של גוף הבקשה הסופי.

קודי מצב HTTP

ממשקי API רגילים של Payments נועדו להחזיר קוד סטטוס HTTP 200 לכל הבקשות שהשרת יכול לעבד. האיסור הזה כולל לבקשות שבוצעו בהצלחה ושנדחו, מבחינת העסק, של הלוגיקה של האפליקציות. בקשות שלא ניתן לעבד לא אמורות להוביל קוד הסטטוס 200 של HTTP כי הם מייצגים שגיאה בין Google שותף. במקום זאת, תגובת ה-API צריכה להשתמש בסטטוס ה-HTTP המתאים הקודים שבהמשך עם אובייקט ErrorResponse אופציונלי.

שגיאות וסיבות ל-HTTP
400 BAD REQUEST

הלקוח ציין ארגומנט לא חוקי.

אפשר גם לקבל את הערך הזה אם הפעולה נדחתה כי המערכת אינו במצב הנדרש לביצוע הפעולה.

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

401 UNAUTHORIZED

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

403 FORBIDDEN / PERMISSION DENIED

למשתמש ששלח את הקריאה אין הרשאה לבצע את הפעולה שצוינה.

404 NOT FOUND

לא נמצאה ישות מבוקשת כמו תשלום או משתמש.

409 CONFLICT / ABORTED

הפעולה בוטלה, בדרך כלל עקב בעיה בו-זמניות (concurrency), כמו כשלים בבדיקת הרצף, ביטולי עסקאות וכו'.

412 PRECONDITION FAILED

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

429 RESOURCE EXHAUSTED / TOO MANY REQUESTS

חלק ממשאבי המערכת אזלו.

499 CANCELLED

הפעולה בוטלה (בדרך כלל על ידי המתקשר/ת).

500 INTERNAL ERROR

שגיאות פנימיות. כלומר, משתנים קבועים מסוימים הצפויים על ידי המערכת הבסיסית שבורה.

501 UNIMPLEMENTED

הפעולה אינה מוטמעת, נתמכת או מופעלת בשירות זה.

503 UNAVAILABLE

השירות הזה לא זמין כרגע. סביר להניח שמדובר במצב זמני וייתכן שיתוקנו על ידי ניסיון חוזר.

504 GATEWAY TIMEOUT / DEADLINE EXCEEDED

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

בקשת אידמפוטנטיות

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

ה-API שלנו משתמש באידמפוטנטיות כדי:

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

דוגמאות

דוגמה 1: הקישוריות אבדה לפני שהתקבלה תשובה

תרחיש:

  1. Google שולחת בקשה למבצע השילוב.
  2. שרת המטמיע מקבל את הבקשה הזו ומעבד אותה בהצלחה.
  3. אספקת החשמל לשרת של Google מתרוקנת לפני שהוא מקבל את התגובה בשלב 2.
  4. אספקת החשמל של השרת של Google מתחדשת ואותה הבקשה נשלחת עם כל אותם הפרמטרים (אותו מזהה בקשה ופרטי בקשה, אבל עודכנה requestTimestamp) לשרת של מבצע השילוב.

התוצאה:

במקרה כזה, שרת השילוב חייב להשיב עם אותה התשובה שסופקה ב- שלב 2: מכיוון שכל הפרמטרים, מלבד responseTimestamp, זהים. תופעת הלוואי מתרחשת פעם אחת בלבד, בשלב 2. לשלב 4 אין השפעה לוואי.

דוגמה 2: הבקשה נשלחה לשרת שעוברת תחזוקה

תרחיש:

  1. מסד הנתונים של שרת השילוב מושבת לצורך תחזוקה.
  2. Google שולחת בקשה למבצע השילוב.
  3. כלי השילוב מחזיר בצורה תקינה את קוד הסטטוס UNAVAILABLE.
  4. השרת של Google מקבל את התגובה ומתזמן ניסיון חוזר.
  5. מסד הנתונים של שרת השילוב יחזור לאינטרנט.
  6. Google שולחת מחדש את הבקשה משלב 2 (אותו מזהה בקשה ופרטי בקשה) אבל עודכן ב-requestTimestamp). שימו לב שמזהי הבקשות של שתי הבקשות צריכים להיות זהים.
  7. שרת השילוב מקבל בקשה ומחזיר יחד עם קוד הסטטוס 'אישור' עם תגובה מלאה.

התוצאה:

במקרה כזה, שרת השילוב חייב לעבד את הבקשה בשלב 7, ולא החזרת HTTP 503 (UNAVAILABLE). במקום זאת, שרת השילוב צריך להיות מלא לעבד את הבקשה ולהחזיר את הבקשה בצורה תקינה עם המסר המתאים. שימו לב שבזמן המערכת היא UNAVAILABLE. Google עשויה לשלוח בקשות חוזרות, בדומה ל- שלב 2. כל בקשה צריכה להוביל להודעה שדומה לשלב 3. בסופו של דבר, שלב 6 ושלב 7 יתבצעו.

דוגמה 3: ההודעה החוזרת לא תואמת להודעה הראשונית עקב שגיאת שחזור

תרחיש:

  1. Google שולחת בקשה למבצע השילוב.
  2. שרת המטמיע מקבל את הבקשה הזו ומעבד אותה בהצלחה.
  3. אספקת החשמל לשרת של Google מתרוקנת לפני שהוא מקבל את התגובה בשלב 2.
  4. אספקת החשמל של השרת של Google משוחזרת ומנסה לשלוח את אותה הבקשה אבל לצערנו חלק מהפרמטרים שונים.

התוצאה:

במקרה הזה, שרת השילוב צריך להשיב עם HTTP 412 (PRECONDITION FAILED) קוד שגיאה שמציין ל-Google שקיימת שגיאה במערכת הזו.