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

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

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

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

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

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

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

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

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

קריאה נוספת

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

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