Package google.assistant.embedded.v1alpha1

אינדקס

EmbeddedAssistant

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

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

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

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

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.DIALOG_FOLLOW_ON
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

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

  • ConverseRequest.config
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseRequest.audio_in
  • ConverseResponse.event_type.END_OF_UTTERANCE
  • ConverseResponse.result.microphone_mode.CLOSE_MICROPHONE
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out
  • ConverseResponse.audio_out

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

הרשאות

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

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

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

AudioInConfig

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

שדות
encoding

Encoding

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

sample_rate_hertz

int32

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

קידוד

קידוד האודיו של הנתונים שנשלחים בהודעת האודיו. האודיו חייב להיות בערוץ אחד (מונו). השפה היחידה שנתמכת היא 'en-US'.

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

AudioOut

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

שדות
audio_data

bytes

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

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).

ConverseConfig

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

שדות
audio_in_config

AudioInConfig

חובה מציין איך לעבד את קטע האודיו הנכנס.

audio_out_config

AudioOutConfig

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

converse_state

ConverseState

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

ConverseRequest

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

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

ConverseConfig

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

audio_in

bytes

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

ConverseResponse

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

שדות
שדה איחוד converse_response. בדיוק אחד מהשדות האלה יאוכלס בכל ConverseResponse. הערך של converse_response יכול להיות רק אחת מהאפשרויות הבאות:
error

Status

פלט בלבד אם הוא מוגדר, מחזירה הודעת google.rpc.Status שמציינת את השגיאה בפעולה. אם תתרחש שגיאה במהלך העיבוד, ההודעה הזו תוגדר ולא יישלחו הודעות נוספות.

event_type

EventType

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

audio_out

AudioOut

פלט בלבד: האודיו שמכיל את התשובה של העוזר הדיגיטלי לשאילתה.

result

ConverseResult

פלט בלבד התוצאה הסמנטית של השאילתה המדוברת של המשתמש.

EventType

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

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

ConverseResult

התוצאה הסמנטית של השאילתה המדוברת של המשתמש.

שדות
spoken_request_text

string

פלט בלבד: התמליל המזוהה של מה שהמשתמש אמר.

spoken_response_text

string

פלט בלבד: הטקסט של התשובה המדוברת של ה-Assistant. השדה הזה מוחזר רק עבור פעולת IFTTT.

conversation_state

bytes

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

microphone_mode

MicrophoneMode

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

volume_percentage

int32

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

MicrophoneMode

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

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

ConverseState

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

שדות
conversation_state

bytes

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