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

כפי שמתואר בקטע הצהרת פעולות, כשמשתמש יוצר אינטראקציה עם פעולה בתוך האפליקציה, 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>

כשהמשתמש ילחץ על הלחצן, תישלח מ-Google בקשת HTTP לשירות שלכם, שבה תתועד האישור. השירות שלכם מקבל את בקשת ה-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: עיבוד הפעולה

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

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

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

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

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

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

מקורות מידע נוספים