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

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

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

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

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

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

קריאה נוספת