Package google.assistant.embedded.v1alpha2

אינדקס

EmbeddedAssistant

שירות שמטמיע את Google Assistant API.

אסיסט

rpc Assist(AssistRequest) returns (AssistResponse)

מתחיל או ממשיך שיחה עם שירות Assistant המוטמע. כל שיחה מבצעת "הלוך ושוב" אחת, שולחת בקשת אודיו לשירות ומקבלת את תגובת האודיו. נעשה שימוש בסטרימינג דו-כיווני כדי לקבל תוצאות, כמו האירוע END_OF_UTTERANCE, בזמן שליחת אודיו.

שיחה היא חיבור אחד או יותר ל-gRPC, שכל אחד מהם מכיל כמה בקשות ותגובות שמשודרות בסטרימינג. לדוגמה, המשתמש אומר Add to my shopping list (הוספה לרשימת הקניות) ו-Assistant משיב מה אתם רוצים להוסיף?. הרצף של הבקשות והתגובות שהועברו בסטרימינג בהודעת ה-gRPC הראשונה יכול להיות:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.speech_results.transcript "add to my shopping list"
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

המשתמש אומר בייגלים ו-Assistant עונה אוקיי, הוספתי בייגלים לרשימת הקניות שלכם. ההודעה הזו נשלחת כקריאה נוספת לחיבור gRPC ל-method Assist, שוב עם בקשות ותגובות שמשודרות בסטרימינג, כמו:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.dialog_state_out.microphone_mode.CLOSE_MICROPHONE
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

למרות שהסדר המדויק של התשובות אינו מובטח, הודעות AssistResponse.audio_out ברצף תמיד יכילו חלקים רציפים של אודיו.

היקפי הרשאות

נדרש היקף OAuth הבא:

  • https://www.googleapis.com/auth/assistant-sdk-prototype

למידע נוסף, עיין במדריך האימות.

AssistConfig

ההגדרה קובעת איך לעבד את ההודעות שנשלחו דרך AssistRequest.

שדות
audio_out_config

AudioOutConfig

חובה מציין את הפורמט של האודיו שיוחזר.

screen_out_config

ScreenOutConfig

אופציונלי מציין את הפורמט הרצוי לשימוש כאשר השרת מחזיר תגובה חזותית של המסך.

dialog_state_in

DialogStateIn

חובה מייצג את המצב הנוכחי של תיבת הדו-שיח.

device_config

DeviceConfig

תצורת מכשיר שמאפשרת לזהות מכשיר ספציפי באופן ייחודי.

debug_config

DebugConfig

אופציונלי פרמטרים של ניפוי באגים לכל ה-RPC Assist.

שדה איחוד type.

הערך של type יכול להיות רק אחת מהאפשרויות הבאות:
audio_in_config

AudioInConfig

ההגדרה קובעת איך לעבד את הקלטות האודיו הנכנסות הבאות. נדרש אם הבקשות הבאות יסופקו AssistRequest.audio_in בייט.

text_query

string

קלט הטקסט שיישלח אל Assistant. אפשר לאכלס אותו בממשק טקסט אם קלט אודיו לא זמין.

AssistRequest

ההודעה ברמה העליונה שנשלחה על ידי הלקוח. לקוחות חייבים לשלוח לפחות שתיים, ולרוב מספר הודעות AssistRequest. ההודעה הראשונה חייבת להכיל הודעת config ולא יכולה להכיל נתונים מסוג audio_in. כל ההודעות הבאות חייבות להכיל נתונים מסוג audio_in ולא יכולות להכיל הודעת config.

שדות
שדה איחוד type. בכל שדה AssistRequest יש לציין בדיוק אחד מהשדות האלה. הערך של type יכול להיות רק אחת מהאפשרויות הבאות:
config

AssistConfig

ההודעה config מספקת מידע למזהה שמציין איך לעבד את הבקשה. ההודעה הראשונה AssistRequest חייבת להכיל הודעת config.

audio_in

bytes

נתוני האודיו שיש לזהות. קטעים רציפים של נתוני אודיו נשלחים בהודעות AssistRequest ברצף. הודעת AssistRequest הראשונה לא יכולה להכיל נתונים מסוג audio_in וכל ההודעות הבאות מסוג AssistRequest חייבות להכיל נתונים מסוג audio_in. הבייטים של האודיו צריכים להיות מקודדים כפי שצוין ב-AudioInConfig. יש לשלוח את האודיו בערך בזמן אמת (16,000 דגימות לשנייה). תוחזר שגיאה אם האודיו נשלח מהר יותר או לאט יותר באופן משמעותי.

AssistResponse

ההודעה ברמה העליונה שהתקבלה על ידי הלקוח. סדרה של הודעת AssistResponse אחת או יותר משודרות בחזרה ללקוח.

שדות
event_type

EventType

פלט בלבד מציין את סוג האירוע.

audio_out

AudioOut

פלט בלבד: האודיו שמכיל את התשובה של Assistant לשאילתה.

screen_out

ScreenOut

פלט בלבד מכיל את התגובה החזותית של ה-Assistant לשאילתה.

device_action

DeviceAction

פלט בלבד מכיל את הפעולה שהופעלה על ידי השאילתה עם מטענים ייעודיים (payloads) וניתוח סמנטי מתאימים.

speech_results[]

SpeechRecognitionResult

פלט בלבד: רשימה חוזרת זו מכילה אפס תוצאות של זיהוי דיבור או יותר. תוצאות אלה תואמות לחלקים רצופים של האודיו שמעובדים כרגע, החל מהקטע התואם לאודיו המוקדם ביותר (והחלק היציב ביותר) לחלק שמתאים לאודיו העדכני ביותר. אפשר לשרשר את המחרוזות כדי להציג את התגובה המלאה שמתקבלת. כשזיהוי הדיבור יושלם, הרשימה תכיל פריט אחד עם stability מתוך 1.0.

dialog_state_out

DialogStateOut

פלט בלבד מכיל פלט שקשור לשאילתת המשתמש.

debug_info

DebugInfo

מידע על ניפוי באגים בפלט בלבד למפתחים. מוחזר רק אם הבקשה הגדירה את return_debug_info כ-True.

EventType

מציין את סוג האירוע.

טיפוסים בני מנייה (enums)
EVENT_TYPE_UNSPECIFIED לא צוין אירוע.
END_OF_UTTERANCE אירוע זה מציין שהשרת זיהה את סוף הדיבור של המשתמש ואינו מצפה לדיבור נוסף. לכן השרת לא יעבד אודיו נוסף (למרות שהוא עשוי להחזיר לאחר מכן תוצאות נוספות). הלקוח צריך להפסיק לשלוח נתוני אודיו נוספים, לסגור חלקית את חיבור ה-gRPC ולהמתין לתוצאות נוספות עד שהשרת סוגר את חיבור ה-gRPC.

AudioInConfig

המדיניות קובעת איך לעבד את נתוני audio_in שיסופקו בבקשות הבאות. ההגדרות המומלצות מופיעות בשיטות המומלצות של Google Assistant SDK.

שדות
encoding

Encoding

נדרש קידוד של נתוני אודיו שנשלחים בכל ההודעות מסוג audio_in.

sample_rate_hertz

int32

קצב הדגימה הנדרש (בהרץ) של נתוני האודיו שנשלחו בכל ההודעות מסוג audio_in. הערכים החוקיים הם 16,000-24,000, אבל 16,000 הוא הערך האופטימלי. לקבלת התוצאות הטובות ביותר, יש להגדיר את קצב הדגימה של מקור האודיו ל-Hz 16,000. אם זה לא אפשרי, כדאי להשתמש בקצב הדגימה המקורי של מקור האודיו (במקום לדגום מחדש).

קידוד

קידוד האודיו של הנתונים שנשלחים בהודעת האודיו. האודיו חייב להיות בערוץ אחד (מונו).

טיפוסים בני מנייה (enums)
ENCODING_UNSPECIFIED לא צוין. תחזיר את התוצאה google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 דגימות קטנות אנדיאניות חתומות של 16 ביט לא דחוסות (PPCM לינארי). הקידוד הזה לא כולל כותרת, אלא רק בייטים של אודיו גולמי.
FLAC FLAC (קודק אודיו ללא אובדן נתונים) הוא הקידוד המומלץ כי הוא חסר אובדן--ולכן הזיהוי לא נפגע--מצריך רק כחצי מרוחב הפס של LINEAR16. הקידוד הזה כולל את כותרת השידור FLAC ואחריה נתוני אודיו. הוא תומך בדוגמאות של 16 ביט ו-24 ביט, אבל לא כל השדות ב-STREAMINFO נתמכים.

AudioOut

קטע האודיו שמכיל את התשובה של Assistant לשאילתה. קטעים רציפים של נתוני אודיו מתקבלים בהודעות AssistResponse ברצף.

שדות
audio_data

bytes

פלט בלבד: נתוני האודיו שמכילים את התשובה של Assistant לשאילתה. קטעים רציפים של נתוני אודיו מתקבלים בהודעות AssistResponse ברצף.

AudioOutConfig

מפרט את הפורמט הרצוי שהשרת ישתמש בו כשמחזירים הודעות audio_out.

שדות
encoding

Encoding

חובה הקידוד של נתוני האודיו שיש להחזיר בכל ההודעות audio_out.

sample_rate_hertz

int32

חובה: תדירות הדגימה בהרץ של נתוני האודיו שהוחזרו בהודעות audio_out. הערכים החוקיים הם: 16,000-24,000.

volume_percentage

int32

חובה: ההגדרה הנוכחית של עוצמת הקול לפלט האודיו של המכשיר. הערכים החוקיים הם 1 עד 100 (תואמים ל-1% עד 100%).

קידוד

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

טיפוסים בני מנייה (enums)
ENCODING_UNSPECIFIED לא צוין. תחזיר את התוצאה google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 דגימות קטנות אנדיאניות חתומות של 16 ביט לא דחוסות (PPCM לינארי).
MP3 קידוד אודיו MP3. קצב הדגימה מקודד במטען הייעודי (payload).
OPUS_IN_OGG אודיו בקידוד אופוס ארוז בקונטיינר ogg. התוצאה תהיה קובץ שאפשר להפעיל באופן מקומי ב-Android ובדפדפנים מסוימים (כמו Chrome). איכות הקידוד גבוהה משמעותית מ-MP3 תוך שימוש באותו קצב העברת נתונים. קצב הדגימה מקודד במטען הייעודי (payload).

DebugConfig

פרמטרים של ניפוי באגים לבקשה הנוכחית.

שדות
return_debug_info

bool

אם השדה הזה מוגדר כ-True, ניתן לאכלס את השדה debug_info בטבלה AssistResponse. עם זאת, זמן האחזור של התשובות יתארך באופן משמעותי.

DebugInfo

מידע על תוצאות ניפוי הבאגים עבור המפתח. מוחזר רק אם הבקשה הגדירה את return_debug_info כ-True.

שדות
aog_agent_to_assistant_json

string

תגובת ה-JSON המקורית מסוכן Action-on-Google לשרת של Google. למידע נוסף, ניתן לעיין בקטע AppResponse. השדה הזה יאוכלס רק אם יוצר הבקשות הוא הבעלים של פרויקט AoG ופרויקט AoG נמצא במצב תצוגה מקדימה.

DeviceAction

התגובה הוחזרה למכשיר אם המשתמש הפעיל פעולה במכשיר. לדוגמה, מכשיר שתומך בשאילתה Turn on the light (הפעלת התאורה) יקבל DeviceAction עם מטען ייעודי (payload) של JSON שמכיל את הסמנטיקה של הבקשה.

שדות
device_request_json

string

קובץ JSON שמכיל את תגובת הפקודה במכשיר שנוצרה מהדקדוק של פעולת המכשיר שהופעל. הפורמט נקבע על ידי ה-Intent action.devices.EXECUTE עבור trait נתון.

DeviceConfig

חובה: שדות שמאפשרים ל-Assistant לזהות את המכשיר.

לעיונך:

שדות
device_id

string

חובה מזהה ייחודי למכשיר. המזהה יכול לכלול 128 תווים לכל היותר. דוגמה: DBCDW098234. הערך הזה חייב להיות זהה ל-device_id שהוחזר מרישום המכשיר. ה-device_id הזה משמש להתאמה עם המכשירים הרשומים של המשתמש, כדי לחפש את התכונות והיכולות הנתמכות של המכשיר הזה. המידע הזה לא אמור להשתנות בין הפעלות מחדש של המכשירים. עם זאת, לא כדאי לשמור את הנתונים באיפוס להגדרות המקוריות.

device_model_id

string

חובה מזהה ייחודי לדגם המכשיר. השילוב של device_model_id ו-device_id היה צריך להיות משויך בעבר באמצעות רישום המכשיר.

DeviceLocation

יש שלושה מקורות של מיקומים. נעשה בהם שימוש עם הקדימות הבאה:

  1. המכשיר DeviceLocation, שמשמש בעיקר מכשירים ניידים עם GPS .
  2. המיקום שצוין על ידי המשתמש במהלך הגדרת המכשיר, הוא לפי משתמש ולפי מכשיר. המיקום הזה יהיה בשימוש אם לא צוין DeviceLocation.
  3. המיקום המשוער מבוסס על כתובת ה-IP. האפשרות הזו משמשת רק אם אף אחת מהאפשרויות שלמעלה לא צוינה.
שדות
coordinates

LatLng

קווי האורך והרוחב של המכשיר.

DialogStateIn

מספק מידע על המצב הנוכחי של תיבת הדו-שיח.

שדות
conversation_state

bytes

חובה תמיד צריך להגדיר בשדה הזה את הערך DialogStateOut.conversation_state שהוחזר ב-RPC הקודם מסוג Assist. יש להשמיט אותה (שדה לא מוגדר) רק אם לא הייתה RPC קודם מסוג Assist כי זו ה-RPC הראשון ב-Assist שבוצע על ידי המכשיר הזה אחרי ההגדרה הראשונה ו/או איפוס להגדרות המקוריות.

language_code

string

חובה שפה של הבקשה בתחביר IETF BCP 47 (לדוגמה, 'en-US'). מידע נוסף זמין בתמיכה בשפות. אם בחרת שפה לdevice_id באמצעות התפריט הגדרות באפליקציית Google Assistant בטלפון, הבחירה הזו תבטל את הערך.

device_location

DeviceLocation

אופציונלי: מיקום המכשיר שבו בוצעה השאילתה.

is_new_conversation

bool

אופציונלי אם הערך הוא True, השרת יתייחס לבקשה כשיחה חדשה ולא ישתמש במצב מהבקשה הקודמת. יש להגדיר את השדה הזה כ-true כשצריך להפעיל מחדש את השיחה, למשל לאחר הפעלה מחדש של המכשיר או לאחר פרק זמן משמעותי מאז השאילתה הקודמת.

DialogStateOut

המצב של תיבת הדו-שיח שנובעת משאילתת המשתמש. ייתכן שיתקבלו מספר רב של הודעות כאלה.

שדות
supplemental_display_text

string

פלט בלבד טקסט משלים לתצוגה מ-Assistant. השם יכול להיות זהה לדיבור שנאמר ב-AssistResponse.audio_out, או שהוא יכול להיות מידע נוסף שיעזור למשתמש להבין את מה שנאמר.

conversation_state

bytes

פרטי מצב פלט בלבד עבור ה-RPC הבא מסוג Assist. יש לשמור את הערך הזה בלקוח ולהחזיר אותו בשדה DialogStateIn.conversation_state עם ה-RPC הבא ב-Assist. (הלקוח לא נדרש לפרש את הערך הזה או להשתמש בו בדרך אחרת). צריך לשמור את המידע הזה בכל הפעלות מחדש של המכשירים. עם זאת, צריך לנקות את הערך הזה (לא לשמור אותו בלקוח) במהלך איפוס להגדרות המקוריות.

microphone_mode

MicrophoneMode

פלט בלבד ההגדרה קובעת את מצב המיקרופון אחרי עיבוד ה-RPC הזה מסוג Assist.

volume_percentage

int32

פלט בלבד עודכנה עוצמת הקול. הערך יהיה 0 או יושמט (כלומר, ללא שינוי), אלא אם זוהתה פקודה קולית כמו הגברת עוצמת הקול או הגדרת עוצמת קול 4. במקרה כזה הערך יהיה בין 1 ל-100 (בהתאם לרמה החדשה של עוצמת הקול, בין 1% ל-100%). בדרך כלל, לקוח צריך להשתמש בעוצמת הקול הזו בעת הפעלת הנתונים של audio_out, ולשמור על הערך הזה כעוצמת עוצמת הקול הנוכחית ולספק אותו ב-AudioOutConfig של ה-AssistRequest הבאים. (לקוחות מסוימים עשויים גם להשתמש בדרכים אחרות כדי לאפשר שינוי של רמת עוצמת הקול הנוכחית, למשל, על ידי הוספת ידית שהמשתמש יכול לסובב).

MicrophoneMode

מצבים אפשריים של המיקרופון לאחר סיום RPC של Assist.

טיפוסים בני מנייה (enums)
MICROPHONE_MODE_UNSPECIFIED לא צוין מצב.
CLOSE_MICROPHONE השירות לא מצפה לשאלת המשך מהמשתמש. המיקרופון צריך להישאר כבוי עד שהמשתמש יפעיל אותו מחדש.
DIALOG_FOLLOW_ON השירות מצפה לשאלת המשך מהמשתמש. צריך לפתוח מחדש את המיקרופון כשההפעלה של AudioOut תסתיים (כדי לשלוח את האודיו החדש ב-Assist צריך להתחיל קריאה חדשה ל-RPC).

ScreenOut

תגובת הפלט החזותי של Assistant לשאילתה. הופעל על ידי screen_out_config.

שדות
format

Format

פלט בלבד: הפורמט של נתוני המסך שסופקו.

data

bytes

פלט בלבד: נתוני המסך הגולמיים שיוצגו כתוצאה מהשאילתה של Assistant.

פורמט

פורמטים אפשריים של נתוני המסך.

טיפוסים בני מנייה (enums)
FORMAT_UNSPECIFIED לא צוין פורמט.
HTML הנתונים יכללו פריסת HTML5 בפורמט מלא ומקודדת ב-UTF-8, לדוגמה: <html><body><div>...</div></body></html>. הוא מיועד לעיבוד יחד עם תגובת האודיו. הערה: ה-doctype של HTML5 צריך להיכלל בנתוני ה-HTML בפועל.

ScreenOutConfig

מפרט את הפורמט הרצוי שהשרת ישתמש בו כשמחזירים את התגובה screen_out.

שדות
screen_mode

ScreenMode

מצב המסך החזותי הנוכחי של המכשיר בזמן הרצת השאילתה.

ScreenMode

מצבים אפשריים של פלט מסך חזותי במכשיר.

טיפוסים בני מנייה (enums)
SCREEN_MODE_UNSPECIFIED לא צוין מצב וידאו. Assistant עשויה להגיב כאילו היא במצב OFF.
OFF המסך כבוי (או שהבהירות שלו או הגדרות אחרות שנקבעו כה נמוכה עד שאי אפשר לראות אותו). לרוב, Assistant לא תחזיר תגובה מהמסך במצב הזה.
PLAYING לרוב, Assistant תחזיר תגובה במסך חלקי במצב הזה.

SpeechRecognitionResult

התמלול המשוער של ביטוי שהמשתמש נאמר. זה יכול להיות קטע יחיד או הניחוש המלא של השאילתה המדוברת של המשתמש.

שדות
transcript

string

פלט בלבד טקסט תמליל שמייצג את המילים שהמשתמש אמר.

stability

float

פלט בלבד: הערכה של הסבירות ש-Assistant לא תשנה את הניחוש שלה לגבי התוצאה הזו. הערכים נעים בין 0.0 (לא יציב לגמרי) ל-1.0 (יציב וסופי לחלוטין). ערך ברירת המחדל של 0.0 הוא ערך סנטינל שמציין ש-stability לא הוגדר.