טיפול בבקשות לפעולות

כפי שמתואר בהצהרת פעולות, כשמשתמש מקיים אינטראקציה עם פעולה בתוך האפליקציה, Google שולחת בקשת HTTP לכתובת URL שהוצהרה בפעולה.

בדוגמה הבאה מוסיפים לחצן ConfirmAction לאימייל לגבי דוח הוצאות:

JSON-LD

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "EmailMessage",
  "potentialAction": {
    "@type": "ConfirmAction",
    "name": "Approve Expense",
    "handler": {
      "@type": "HttpActionHandler",
      "url": "https://myexpenses.com/approve?expenseId=abc123"
    }
  },
  "description": "Approval request for John's $10.13 expense for office supplies"
}
</script>

מיקרו נתונים

<div itemscope itemtype="http://schema.org/EmailMessage">
  <div itemprop="potentialAction" itemscope itemtype="http://schema.org/ConfirmAction">
    <meta itemprop="name" content="Approve Expense"/>
    <div itemprop="handler" itemscope itemtype="http://schema.org/HttpActionHandler">
      <link itemprop="url" href="https://myexpenses.com/approve?expenseId=abc123"/>
    </div>
  </div>
  <meta itemprop="description" content="Approval request for John's $10.13 expense for office supplies"/>
</div>

כשהמשתמש ילחץ על הלחצן, תישלח בקשת HTTP מ-Google לשירות שלכם, שמתעד את האישור. השירות שלכם מקבל את בקשת ה-HTTP הבאה מ-Google:

POST /approve?expenseId=abc123 HTTP/1.1
Host: your-domain.com
Authorization: Bearer AbCdEf123456
Content-Type: application/x-www-form-urlencoded
User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions)

confirmed=Approved

בהמשך הדף מוסבר מה השירות ב-https://your-domain.com/approve?expenseId=abc123 צריך לעשות כדי לטפל בפעולה כראוי. האיסור הזה כולל:

  • מאמת את הבקשה
  • מתבצע עיבוד של המטען הייעודי (payload)
  • החזרת קוד תגובה

שלב 1: מאמתים את הבקשה

השירות ב-https://your-domain.com/approve?expenseId=abc123 מומלץ לבדוק:

סוכן המשתמש לכל הבקשות לפעולה הוא Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/1.0 (KHTML, like Gecko; Gmail Actions).

אם כל הבדיקות עוברות בהצלחה, השירות יכול להמשיך לשלב הבא.

שלב 2: עבד את הפעולה

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

מידע נוסף מהמשתמש נמצא בגוף הבקשה, ומקודד באמצעות הקידוד x-www-form-urlecoded. המידע מוגדר בנכסים שהשמות שלהם תואמים למאפיינים של Action. לדוגמה, ConfirmAction כולל את המאפיין confirmed.

שלב 3: החזרת קוד תגובה

לאחר שהשירות יעובד ויקליט את הפעולה בהצלחה, הוא אמור להחזיר קוד תגובה 200 (OK). ניתן להשתמש בקודי התגובה הבאים במצבי שגיאה:

קוד תגובה טיפול
400 (בקשה שגויה) Google תיכשל בפעולה זו.
401 (אין הרשאה) Google תיכשל בפעולה זו.
404 (לא נמצא) Google תיכשל בפעולה זו.
408 (תם הזמן הקצוב לתפוגה של הבקשה) Google תנסה שוב מאוחר יותר.

במקרה של כשל קבוע, Google תודיע למשתמש שהפעולה נכשלה ועליו לבצע את ההוראות החלופיות המופיעות בהודעת האימייל.

קריאה נוספת