Google Assistant Library

החבילה google.assistant.library.

class google.assistant.library.Assistant(credentials, device_model_id)

לקוח לספריית Google Assistant.

ממשק שמספק פונקציונליות בקרה בסיסית וטיפול במחזור החיים של Google Assistant. מומלץ להשתמש ב-Assistant בתור ContextManager:

with Assistant(credentials, device_model_id) as assistant:

כך ההטמעה המקורית שבבסיס יכולה לטפל בצורה נכונה בניהול הזיכרון.

אחרי שמפעילים את start(), Assistant יוצרת פלט של אירועים שמעבירים את המצבים השונים שבהם היא נמצאת כרגע. לדוגמה:

ON_CONVERSATION_TURN_STARTED
ON_END_OF_UTTERANCE
ON_RECOGNIZING_SPEECH_FINISHED:
    {'text': 'what time is it'}
ON_RESPONDING_STARTED:
    {'is_error_response': False}
ON_RESPONDING_FINISHED
ON_CONVERSATION_TURN_FINISHED:
    {'with_follow_on_turn': False}

פרטים על כל האירועים והארגומנטים שלהם מופיעים במאמר EventType.

מילון מונחים:

  • מילת הפעלה: הביטוי ש-Assistant מאזינה לו כשהיא לא מושתקת:

    "OK Google" OR "Hey Google"

  • פנייה: בקשה אחת של משתמש ואחריה תגובה מ-Assistant.

  • שיחה: תור אחד או יותר שמובילים לתוצאה סופית רצויה מ-Assistant:

    "What time is it?" -> "The time is 6:24 PM" OR
"Set a timer" -> "Okay, for how long?" ->
"5 minutes" -> "Sure, 5 minutes, starting now!"
פרמטרים:
  • credentials (google.oauth2.credentials.Credentials) – פרטי הכניסה של המשתמש ב-Google OAuth2.
  • device_model_id (str) – מזהה device_model_id שרשום לפרויקט שלכם ב-Google. המחרוזת הזו לא יכולה להיות ריקה.
העלאות:

ValueError – אם השארתם את device_model_id כ-None או ריק.
device_id

הפונקציה מחזירה את מזהה המכשיר שנוצר על ידי Assistant.

הערך הזה מזהה את המכשיר שלכם בשרת כשאתם משתמשים בשירותים כמו Google Device Actions. הנכס הזה מתמלא רק אחרי שמפעילים את start().

החזרות:מזהה המכשיר אחרי קריאה ל-start(), או מחרוזת ריקה אחרת.
סוג ההחזרה:str
send_text_query(query)

הפונקציה שולחת את הערך |query| ל-Assistant כאילו המשתמש אמר אותו.

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

פרמטרים:query (str) – שאילתת הטקסט ששולחים ל-Assistant.
set_mic_mute(is_muted)

Assistant לא תאזין למילות ההפעלה.

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

אם Assistant עדיין לא הופעל, השיטה הזו לא תפעל.

פרמטרים:is_muted (bool) – הערך True מפסיק את ההאזנה של Assistant, והערך False מאפשר לה להתחיל שוב.
start()

הפעלת Assistant, כולל האזנה למילת הפעלה.

אחרי הקריאה ל-start(), Assistant תתחיל לעבד נתונים ממקור האודיו 'ברירת המחדל' של ALSA, ותאזין למילה המפעילה. הפעולה הזו תפעיל גם שירותים אחרים של Assistant, כמו טיימרים או שעונים מעוררים. אפשר לקרוא לשיטה הזו רק פעם אחת. אחרי ההפעלה, Assistant תמשיך לפעול עד להפעלת __exit__.

החזרות:תור של אירועים שמעדכנים על שינויים במצב של Assistant.
סוג ההחזרה:google.assistant.event.IterableEventQueue
start_conversation()

התחלת שיחה חדשה עם Assistant באופן ידני.

מתחילה הקלטה של הדיבור של המשתמש ושליחתו ל-Google, בדומה למה שקורה כש-Assistant מזהה את מילת המפתח.

השיטה הזו לא תפעל אם Assistant לא מופעלת או אם היא מושתקת.

stop_conversation()

הפעולה הזו תפסיק כל שיחה פעילה עם Assistant.

יכול להיות ש-Assistant מקשיבה לשאילתה של המשתמש או מגיבה לה. אם אין שיחה פעילה, הפעולה הזו לא תתבצע.

class google.assistant.library.event.AlertEvent(event_type, args, **_)

הרחבה של אירוע כדי להוסיף ניתוח של 'alert_type'.

class google.assistant.library.event.AlertType

סוגי התראות.

נעשה בו שימוש באירועים מסוג ON_ALERT_STARTED ו-ON_ALERT_FINISHED.

ALARM = 0

אירוע שהוגדר לשעה מדויקת, למשל '3:00 לפנות בוקר ביום שני'

TIMER = 1

אירוע שהוגדר לזמן יחסי, למשל '30 שניות מעכשיו'

class google.assistant.library.event.DeviceActionEvent(event_type, args, **kwargs)

הרחבה של אירוע להוספת המאפיין 'פעולות'.

actions

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

class google.assistant.library.event.Event(event_type, args, **_)

אירוע שנוצר על ידי Assistant.

type

EventType – סוג האירוע שנוצר.

args

dict – צמדי מפתח/ערך של ארגומנטים שמשויכים לאירוע הזה.

static New(event_type, args, **kwargs)

יוצרים אירוע חדש באמצעות סוג אירוע ספציפי לפי הצורך.

פרמטרים:
  • event_type (int) – מזהה מספרי שתואם לאירוע ב-google.assistant.event.EventType.
  • args (dict) – צמדי מפתח/ערך של ארגומנטים שמשויכים לאירוע הזה.
  • kwargs (dict) – צמדי מפתח/ערך אופציונליים של ארגומנטים שספציפיים להתמחות של Event class עבור EventType.
class google.assistant.library.event.EventType

סוגי אירועים.

ON_ALERT_FINISHED = 11

מציין שההתראה של alert_type הסתיימה.

פרמטרים:alert_type (AlertType) – המזהה של Enum שמייצג את סוג ההתראה שזה עתה הסתיימה.
ON_ALERT_STARTED = 10

סימן לכך שהתראה התחילה לפעול.

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

פרמטרים:alert_type (AlertType) – המזהה של Enum שמייצג את סוג ההתראה שמופעלת כרגע.
ON_ASSISTANT_ERROR = 12

מציין אם אירעה שגיאה בספריית Assistant.

פרמטרים:is_fatal (bool) – אם הערך הוא True, לא תהיה אפשרות לשחזר את Assistant וצריך להפעיל אותה מחדש.
ON_CONVERSATION_TURN_FINISHED = 9

Assistant סיימה את הפנייה הנוכחית.

הזמן הזה כולל גם את עיבוד השאילתה של המשתמש וגם את הקריאה של התשובה המלאה, אם יש כזו.

פרמטרים:with_follow_on_turn (bool) – אם הערך הוא True, Assistant מצפה לאינטראקציה נוספת מהמשתמש. המיקרופון ייפתח מחדש כדי לאפשר למשתמש לענות על שאלה נוספת.
ON_CONVERSATION_TURN_STARTED = 1

סימן לכך שפנייה חדשה מתחילה.

Assistant מאזינה כרגע ומחכה לשאילתה של המשתמש. יכול להיות שהסיבה לכך היא שמילות ההפעלה או start_conversation() נשמעות.

ON_CONVERSATION_TURN_TIMEOUT = 2

תם פרק הזמן שהוקצב להמתנה לשאילתה שניתן להבין.

הסיבה לכך יכולה להיות הפעלה שגויה של מילת המפתח או ש-Assistant לא הצליחה להבין את מה שהמשתמש אמר.

ON_DEVICE_ACTION = 14

הסטטוס הזה מציין שנשלחה למכשיר בקשה לפעולה במכשיר.

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

פרמטרים:dict – המטען הייעודי (payload) של ה-JSON שעבר פענוח של בקשה לפעולה במכשיר.
ON_END_OF_UTTERANCE = 3

Assistant הפסיקה להאזין לשאילתה של משתמש.

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

ON_MEDIA_STATE_ERROR = 20

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

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

ON_MEDIA_STATE_IDLE = 16

מציין שאין מדיה שפועלת ואין מדיה בתור להפעלה.

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

ON_MEDIA_TRACK_LOAD = 17

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

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

פרמטרים:
  • metadata (dict) –

    מטא-נתונים של הטראק שנטען. לא כל השדות יאוכלסו עד לאותו מועד – אם שדה מסוים לא ידוע, הוא לא ייכלל. שדות המטא-נתונים כוללים את אלה:

    album(str): שם האלבום שאליו שייך הטראק. album_art(str): כתובת URL של תמונת האלבום. artist(str): האומן שיצר את הטראק. duration_ms(double): אורך הטראק ביחידות אלפיות השנייה. title(str): שם הטראק.
  • track_type (MediaTrackType) – סוג הטראק שנטען.
ON_MEDIA_TRACK_PLAY = 18

מציין שטראק מסוים משדר כרגע אודיו.

האירוע הזה יופעל רק כשנעבור ממצב אחד למצב אחר, למשל מ-ON_MEDIA_TRACK_LOAD או מ-ON_MEDIA_TRACK_STOP

פרמטרים:
  • metadata (dict) –

    מטא-נתונים של הטראק שמוצג. אם השדה לא מוכר, הוא לא ייכלל. שדות המטא-נתונים כוללים את אלה:

    album(str): שם האלבום שאליו שייך הטראק. album_art(str): כתובת URL של תמונת האלבום. artist(str): האומן שיצר את הטראק. duration_ms(double): משך הטראק במילישניות. title(str): שם הטראק.
  • position_ms (double) – המיקום הנוכחי בטראק שפועל, באלפיות שנייה מההתחלה. אם הערך של 'metadata.duration_ms' לא ידוע (מוגדר כ-0), השדה הזה לא יוגדר.
  • track_type (MediaTrackType) – סוג הטראק שמוצג.
ON_MEDIA_TRACK_STOP = 19

הסמל הזה מציין שטראק שהיה מושמע הופסק.

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

פרמטרים:
  • metadata (dict) –

    מטא-נתונים של הטראק שהושבת. אם השדה לא מוכר, הוא לא ייכלל. שדות המטא-נתונים כוללים את אלה:

    album(str): שם האלבום שאליו הטראק שייך. album_art(str): כתובת URL של תמונת האלבום. artist(str): האומן שיצר את הטראק הזה. duration_ms(double): אורך הטראק ביחידות אלפיות השנייה. title(str): שם הטראק.
  • position_ms (double) – המיקום הנוכחי בטראק מושהה, באלפיות שנייה מההתחלה. אם הערך של 'metadata.duration_ms' לא ידוע (מוגדר כ-0), השדה הזה לא יוגדר.
  • track_type (MediaTrackType) – סוג הטראק שהושבת.
ON_MUTED_CHANGED = 13

מציין אם Assistant מאזינה כרגע או לא.

start() תמיד ייצור אירוע ON_MUTED_CHANGED כדי לדווח על הערך הראשוני.

פרמטרים:is_muted (bool) – אם הערך הוא True, המשמעות היא ש-Assistant לא מקשיבה כרגע למילות המפתח שלה ולא תגיב לשאילתות של המשתמשים.
ON_NO_RESPONSE = 8

Assistant השלימה את התור שלה אבל אין לה מה לומר.

ON_RECOGNIZING_SPEECH_FINISHED = 5

Assistant זיהתה את הטקסט הסופי.

פרמטרים:text (str) – הפרשנות הסופית של הטקסט לשאילתה של משתמש.
ON_RENDER_RESPONSE = 15

מציין של-Assistant יש פלט טקסט לעיבוד בתור תשובה.

פרמטרים:
  • type (RenderResponseType) – סוג התגובה לעיבוד.
  • text (str) – המחרוזת לעיבוד עבור RenderResponseType.TEXT.
ON_RESPONDING_FINISHED = 7

Assistant סיימה להגיב באמצעות הקול.

ON_RESPONDING_STARTED = 6

Assistant מתחילה להגיב באמצעות הקול.

Assistant תמשיך להגיב עד שתקבל את ההודעה ON_RESPONDING_FINISHED.

פרמטרים:is_error_response (bool) – הערך True מציין שהמערכת מקריאה TTS של שגיאה מקומית, אחרת Assistant מגיבה בתגובה מהשרת.
ON_START_FINISHED = 0

הספרייה של Assistant הסתיימה.

class google.assistant.library.event.IterableEventQueue(timeout=3600)

הרחבה של queue.Queue להוספת ממשק __iter__.

offer(event)

מציעים אירוע להוספה לתור.

אם התור מלא, האירוע יירשם ביומן אבל לא יתווסף.

פרמטרים:event (Event) – האירוע שרוצים לנסות להוסיף לתור.
class google.assistant.library.event.MediaStateChangeEvent(event_type, args, **_)

הרחבה של Event כדי להוסיף ניתוח של 'state'.

class google.assistant.library.event.MediaTrackType

סוגי הטראקים באירועים מסוג ON_MEDIA_TRACK_X.

בשימוש עם ON_MEDIA_TRACK_LOAD,‏ ON_MEDIA_TRACK_PLAY ו-ON_MEDIA_TRACK_STOP

CONTENT = 2

התוכן בפועל של פריט (חדשות/פודקאסט).

TTS = 1

טראק של קריינות או טראק מעברון שקשור לפריט.

class google.assistant.library.event.RenderResponseEvent(event_type, args, **_)

הרחבה של 'אירוע' להוספת ניתוח של 'response_type'.

class google.assistant.library.event.RenderResponseType

סוגי התוכן לעיבוד.

בשימוש עם ON_RENDER_RESPONSE