יכול להיות שלמכשיר יש יכולות מיוחדות שלא נכללות בקבוצת תכונות -- כמו תכונה של "הבהוב האור" של מכשיר שיכול להבהב באורות. אפשר להגדיר פעולות מותאמות אישית למכשיר שמציינות את הפקודות שנשלחות למכשיר כדי להפעיל יכולות מיוחדות.
כדי להגדיר פעולה מותאמת אישית במכשיר, צריך:
- דפוס להתאמה לשאילתת המשתמש
- פעולה מותאמת אישית במכשיר לשיוך לשאילתה תואמת
- טקסט שמוקרא בחזרה למשתמש אם המכשיר תומך בפעולה
- שם פקודה שנשלחת בחזרה למכשיר יחד עם הפרמטרים
כדי ליצור פעולה מותאמת אישית למכשיר, מזינים את המידע הזה בחבילת פעולות. חבילות פעולה מגדירות את הפורמט של התשובות מ-Assistant. שלא כמו ב-Actions SDK, פעולות מותאמות אישית במכשיר מתבצעות באופן מקומי. לא צריך לציין נקודת קצה (endpoint) לעיבוד בקשות ולמתן תשובות. פעולות מותאמות אישית במכשיר אינן מדוברות מטבען.
יצירה של חבילת פעולה
בעזרת הדוגמה הבאה, יוצרים קובץ (למשל actions.json) שמגדיר פקודת בדיקה: הבהוב נורית LED.
מעתיקים אותו מהקוד לדוגמה שהורדתם בשלב הקודם:
cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/grpc/
cp ~/assistant-sdk-python/google-assistant-sdk/actions.json .
{
"manifest": {
"displayName": "Blinky light",
"invocationName": "Blinky light",
"category": "PRODUCTIVITY"
},
"actions": [
{
"name": "com.example.actions.BlinkLight",
"availability": {
"deviceClasses": [
{
"assistantSdkDevice": {}
}
]
},
"intent": {
"name": "com.example.intents.BlinkLight",
"parameters": [
{
"name": "number",
"type": "SchemaOrg_Number"
},
{
"name": "speed",
"type": "Speed"
}
],
"trigger": {
"queryPatterns": [
"blink ($Speed:speed)? $SchemaOrg_Number:number times",
"blink $SchemaOrg_Number:number times ($Speed:speed)?"
]
}
},
"fulfillment": {
"staticFulfillment": {
"templatedResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Blinking $number times"
}
},
{
"deviceExecution": {
"command": "com.example.commands.BlinkLight",
"params": {
"speed": "$speed",
"number": "$number"
}
}
}
]
}
}
}
}
],
"types": [
{
"name": "$Speed",
"entities": [
{
"key": "SLOWLY",
"synonyms": [
"slowly",
"slow"
]
},
{
"key": "NORMALLY",
"synonyms": [
"normally",
"regular"
]
},
{
"key": "QUICKLY",
"synonyms": [
"quickly",
"fast",
"quick"
]
}
]
}
]
}
בדוגמה הקודמת השתמשנו במידע הבא כדי להגדיר את הפעולה המותאמת אישית במכשיר:
- דפוס שמתאים לשאילתת המשתמש (הבהוב N פעמים)
- הפעולה המותאמת אישית במכשיר לשיוך לשאילתה תואמת (
com.example.actions.BlinkLight) למטרות ארגוניות - טקסט שחוזר אל המשתמש, אם המכשיר תומך בפעולה הזו (מהבהב N פעמים)
- שם פקודה (
com.example.commands.BlinkLight) שנשלחת בחזרה למכשיר יחד עם הפרמטרים (מספר ואולי גם תיאור של המהירות)
כדי להגדיר את דפוס השאילתה, חשוב לשים לב לנקודות הבאות:
- אפשר להשתמש בסוגים שהוגדרו על ידי schema.org בדפוס השאילתה.
- המערך
types [...]מגדיר את רשימת הסוגים המותאמים אישית (לדוגמה,$Speed). - אפשר להשתמש בסוגים מותאמים אישית בדפוס השאילתה. המשתמש יכול לומר כל אחת מהמילים הנרדפות בסוג המותאם אישית כדי להתאים לדפוס השאילתה.
- כשמילה נרדפת תואמת, המופע הסוג (
speed) יחזיר את המפתח המנורמל (SLOWLY). למשל, יכולות להיות כמה ישויות שונות, שתומכות במהירויות שונות של הבהוב. - ניתן להוסיף חלקים מתבנית ה-TTS של הבקשה. לדוגמה, משתמשים ב-
($Speed:speed)?בדפוס השאילתה כדי שהחלק הזה יהיה אופציונלי. $type.raw(לדוגמה,$speed.raw) בתגובה TTS של התשובה מוחלף במילים שהמשתמש דיבר בפועל.
לתיאורים של רבים מהשדות האלה, עיינו במסמכי התיעוד של ActionPackage.
פריסה של חבילת הפעולות
אחרי שיוצרים פעולה מותאמת אישית במכשיר בחבילת Action, אפשר להפוך את חבילת הפעולות לנגישה ל-Assistant.
אמנם ניתן לבצע את השלבים בסעיף הזה במכשיר שלכם, אבל יכול להיות שיהיה קל יותר לבצע אותם במערכת הפיתוח. כדי להפעיל את הפקודות הבאות לא צריך ליצור סביבה וירטואלית.
מורידים את כלי שורת הפקודה
gactions.מסירים את כל פרטי הכניסה הקיימים מאותה ספרייה כמו הכלי
gactions.rm creds.data
שומרים את חבילת הפעולות ב-Google באמצעות ה-CLI
gactions. מחליפים את הערךproject_idב-ID של הפרויקט ב-Actions Console../gactions update --action_package actions.json --project project_id
בפעם הראשונה שתריצו את הפקודה הזו, תקבלו כתובת URL ותתבקשו להיכנס אליה. מעתיקים את כתובת ה-URL ומדביקים אותה בדפדפן (אפשר לעשות זאת בכל מערכת). בדף תתבקשו להיכנס לחשבון Google. נכנסים לחשבון Google שבו יצרתם את הפרויקט בשלב הקודם ( שלב.
אחרי שתאשרו את בקשת ההרשאה מה-API, יופיע בדפדפן קוד כמו '4/XXXX'. מעתיקים ומדביקים את הקוד הזה בטרמינל:
Enter the authorization code:
אם ההרשאה הצליחה, תופיע תגובה שדומה לזו:
Your app for the Assistant for project my-devices-project was successfully updated with your actions.פורסים את חבילת הפעולות במצב בדיקה באמצעות ה-CLI של
gactions. עליכם לשמור את חבילת הפעולות ב-Google לפחות פעם אחת לפני הרצת הפקודה הזו. מצב בדיקה מפעיל את חבילת Action בחשבון המשתמש שלכם בלבד../gactions test --action_package actions.json --project project_id
בשלב זה לא ניתן לבדוק את הפרויקט באמצעות סימולטור הפעולות.
כדי לעדכן את חבילת הפעולות, יש להשתמש בפקודה
gactions update.(אופציונלי) אפשר ליצור חבילות פעולה שמותאמות לשוק המקומי כדי לתמוך בהרבה שפות ולוקאלים שונים בו-זמנית בפרויקט אחד.
שינוי הדוגמה
מבצעים את השלבים שבקטע הזה במכשיר.
nano pushtotalk.py
הוספת handler לפעולה המותאמת אישית. שימו לב שה-handler שבהמשך כבר נוסף לקוד לדוגמה של חבילת הפעולות לדוגמה שלמעלה.
...
device_handler = device_helpers.DeviceRequestHandler(device_id)
@device_handler.command('com.example.commands.BlinkLight')
def blink(speed, number):
logging.info('Blinking device %s times.' % number)
delay = 1
if speed == "SLOWLY":
delay = 2
elif speed == "QUICKLY":
delay = 0.5
for i in range(int(number)):
logging.info('Device is blinking.')
# GPIO.output(25, 1)
time.sleep(delay)
# GPIO.output(25, 0)
time.sleep(1)
הפעלת הדוגמה
מריצים את קוד המקור.
python pushtotalk.py
אפשר לנסות שאילתה. אפשר לנסות את השלבים הבאים בדוגמה שלמעלה:
מצמוץ 5 פעמים.
חשוב לשים לב שהשאילתה צריכה להתאים לתבנית השאילתה בחבילת הפעולות.