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

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

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

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

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:

• אסימון גישה לשימוש מוגבל – כדי להגן מפני התקפות שחזור.
• סוכן משתמש – כדי לוודא שהבקשה מגיעה מ-Google.
• אסימון למוכ"ז – כדי להבטיח שהבקשה מגיעה מ-Google ומתייחסת לשירות.

סוכן המשתמש של כל בקשות הפעולה הוא 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). אפשר להשתמש בקודי התגובה הבאים במצבים של שגיאה:

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

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

• אבטחת פעולות