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

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

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

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

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

קריאה נוספת

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