כפי שמתואר בהצהרת פעולות, כשמשתמש מקיים אינטראקציה עם פעולה בתוך האפליקציה, 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
מומלץ לבדוק:
- Limited Use Access Token (אסימון גישה מוגבל) – להגנה מפני התקפות הפעלה מחדש.
- סוכן משתמש – כדי לוודא שהבקשה מגיעה מ-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 תודיע למשתמש שהפעולה נכשלה ועליו לבצע את ההוראות החלופיות המופיעות בהודעת האימייל.