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

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

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

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

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

שלב 2: עיבוד הפעולה

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

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

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

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

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

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

קריאה נוספת

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

הערה: חלק מהסכימות שבהן Google משתמשת עדיין נמצאות בתהליך התקינה של schema.org, ולכן יכול להיות שהן ישתנו בעתיד. מידע נוסף