Google Assistant Library

حزمة google.assistant.library.

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

برنامج مخصّص لمكتبة "مساعد Google"

توفر وظائف التحكم الأساسية والتعامل مع مراحل النشاط مساعد Google. من أفضل الممارسات استخدام "مساعد Google" ContextManager:

with Assistant(credentials, device_model_id) as assistant:

ويسمح ذلك للتنفيذ الأصلي الأساسي بالتعامل بشكلٍ سليم مع إدارة الذاكرة.

بعد استدعاء start()، يُنشئ "مساعد Google" سلسلة من الأحداث التي تنقل الحالات المختلفة التي يكون فيها "مساعد Google" حاليًا، على سبيل المثال:

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 للاطّلاع على تفاصيل عن جميع الأحداث ووسيطاتها.

المفردات:

  • كلمة تفعيل: العبارة التي يصغي إليها "مساعد Google" عند عدم كتم الصوت:

    "OK Google" OR "Hey Google"

  • دوران: طلب مستخدم واحد متبوعًا بردّ من "مساعد Google"

  • محادثة: منعطف واحد أو أكثر يؤدي إلى الحصول على نتيجة نهائية مطلوبة مِنْ مُسَاعِدْ Google:

    "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 على أنّه "بدون" أو فارغًا.
device_id

تعرِض هذه السمة رقم تعريف الجهاز الذي أنشأه "مساعِد Google".

تُحدِّد هذه القيمة جهازك للخادم عند استخدام الخدمات، مثل "إجراءات أجهزة Google". يتم ملء هذه السمة "بعد" فقط. تم الاتصال بـ start().

المرتجعات:رقم تعريف الجهاز مرة واحدة يحتوي start() على سلسلة فارغة في الحالات الأخرى.
نوع الإرجاع:str
send_text_query(طلب البحث)

تُرسِل |query| إلى "مساعد Google" كما لو كان المستخدم قد نطقها.

سيؤدي ذلك إلى التصرّف بالطريقة نفسها التي يتصرّف بها المستخدم عند قول الكلمة الرئيسية وطرح استعلام أو قول الإجابة عن استعلام لاحق.

المَعلمات:query (str) – طلب البحث النصي المراد إرساله إلى "مساعد Google"
set_mic_mute(is_muted)

إيقاف "مساعد Google" عن الاستماع إلى الكلمة المفتاح

يسمح هذا الخيار بإيقاف "مساعد Google" عن الاستماع إلى الكلمة الرئيسية. يقدّم هذا الزر وظيفة مشابهة لزر الخصوصية في الجهة الخلفية من Google Home.

لا يمكن تنفيذ هذه الطريقة إذا لم يكن "مساعد Google" قد بدأ.

المَعلمات:‫is_muted (bool): تؤدي القيمة True إلى إيقاف "مساعد Google" عن الاستماع، بينما تؤدي القيمة False إلى السماح له بالبدء من جديد.
start()

يؤدي هذا الاختصار إلى تشغيل "مساعد Google"، بما في ذلك الاستماع إلى كلمة تفعيل الإجراء.

بعد start() الاستدعاء، سيبدأ "مساعد Google" في معالجة البيانات من مصدر الصوت ALSA "التلقائي"، وسيتوقّف عن الاستماع إلى الكلمة الرئيسية. سيؤدي ذلك أيضًا إلى بدء خدمات أخرى يوفّرها "مساعد Google"، مثل الموقّتات والمنبّهات. لا يمكن استدعاء هذه الطريقة سوى مرة واحدة. مرة واحدة الاتصال، سيستمر "مساعد Google" في العمل حتى __exit__ البيانات.

المرتجعات:قائمة انتظار بالأحداث التي تُعلِم "مساعد Google" بالتغييرات الولاية.
نوع القيمة التي يتم عرضها:google.assistant.event.IterableEventQueue
start_conversation()

بدء محادثة جديدة يدويًا مع "مساعد Google"

يبدأ تسجيل كلام المستخدم وإرساله إلى Google، مثلما يحدث عندما يسمع "مساعد Google" عبارة الطلب.

لا يمكن تنفيذ هذه الطريقة إذا لم يتم تشغيل "مساعد Google" أو إذا كان قيد التشغيل. كتم الصوت.

stop_conversation()

إيقاف أي محادثة نشطة مع "مساعد Google"

قد يكون "مساعد Google" يستمع إلى طلب المستخدم أو يردّ عليه. إذا لم تكن هناك محادثة نشطة، لن يتم تنفيذ أي إجراء.

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

توسيع Event لإضافة تحليل "alert_type"

class google.assistant.library.event.AlertType

أنواع التنبيهات.

مُستخدَم مع ON_ALERT_STARTED أو ON_ALERT_FINISHED أحداث.

ALARM = 0

حدث مضبوط على وقت مطلق، مثل الساعة "3 صباحًا يوم الاثنين"

TIMER = 1

حدث تم ضبطه على فترة زمنية نسبية مثل "30 ثانية من الآن"

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

توسّع الحدث لإضافة خاصية "الإجراءات".

actions

أداة لإنشاء أوامر لتنفيذها على الجهاز الحالي

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

حدث من إنشاء "مساعد Google".

type

EventType – نوع الحدث الذي تم إنشاؤه.

args

dict – أزواج المفتاح/القيمة للوسيطة المرتبطة بهذا الحدث.

ثابت New(event_type, args, **kwargs)

يمكنك إنشاء حدث جديد باستخدام صف حدث متخصص عند الحاجة.

المَعلمات:
  • event_type (int) – معرّف رقمي يتوافق مع حدث في google.assistant.event.EventType.
  • args (dict) – أزواج المفتاح/القيمة وسيطة مرتبطة بهذا الحدث.
  • kwargs (dict) – أزواج مفتاح/قيمة وسيطة اختيارية خاصة بـ التخصص في فئة الحدث لنوع الحدث.
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

يشير هذا الرمز إلى حدوث خطأ في مكتبة "مساعد Google".

المَعلمات:‫is_fatal (bool): إذا كانت القيمة "صحيح"، لن يتمكّن "مساعد Google" من الاستجابة مجددًا، ويجب إعادة تشغيله.
ON_CONVERSATION_TURN_FINISHED = 9

أكمل "مساعد Google" الدوران الحالي.

ويشمل ذلك معالجة طلب بحث المستخدم وقراءة الردّ الكامل، إن توفّر.

المَعلمات:‫with_follow_on_turn (bool): إذا كانت القيمة "صحيحة"، يعني ذلك أنّ "مساعد Google" يتوقّع من المستخدم تفاعل متابعة. سيتم تشغيل الميكروفون إعادة فتحها للسماح للمستخدم بالإجابة على سؤال المتابعة.
ON_CONVERSATION_TURN_STARTED = 1

يشير إلى بدء منعطف جديد.

"مساعد Google" يستمع حاليًا في انتظار سماع أحد المستخدمين. طلب البحث. قد يكون ذلك نتيجة سماع كلمة التفعيل أو عند start_conversation() الاستدعاء على "مساعد Google".

ON_CONVERSATION_TURN_TIMEOUT = 2

انتهت مهلة "مساعد Google" أثناء انتظار طلب بحث يمكن تمييزه.

قد يرجع سبب ذلك إلى تنشيط عبارة التفعيل عن طريق الخطأ أو عدم تمكّن "مساعد Google" من فهم ما قاله المستخدم.

ON_DEVICE_ACTION = 14

يشير ذلك إلى أنّه تم إرسال طلب إجراء على الجهاز إلى الجهاز.

يتم إرسال هذا الحقل في حال تشغيل أي قاعدة نحوية للجهاز السمات يتوافق مع الجهاز. يحتوي نوع الحدث هذا على سمة "الإجراءات" الخاصة التي ستُعرِض عنصر تكرار أو أوامر "إجراءات الجهاز" والمَعلمات المرتبطة بها (إن وُجدت).

المَعلمات:dict: حمولة JSON التي تم فك ترميزها لطلب إجراء على الجهاز.
ON_END_OF_UTTERANCE = 3

توقّف "مساعد Google" عن الاستماع إلى طلب أحد المستخدمين.

ربما لم ينته "مساعد Google" من معرفة ما يقوله المستخدم، ولكن توقف الاستماع إلى المزيد من البيانات الصوتية.

ON_MEDIA_STATE_ERROR = 20

يشير إلى حدوث خطأ أثناء تشغيل مقطع صوتي.

سيحاول مشغّل الوسائط المدمج الانتقال إلى المقطع الصوتي التالي أو الرجوع إلى ON_MEDIA_STATE_IDLE إذا لم يتبق شيء لتشغيله.

ON_MEDIA_STATE_IDLE = 16

يشير ذلك إلى أنّه ما مِن محتوى مشغَّل أو محتوى في "قائمة المحتوى التالي".

يتمّ بث هذا الحدث من خلال مكتبة "مساعد Google" المدمجة مشغّل وسائط للأخبار أو ملفات البودكاست عند بدء التشغيل وعندما يكون لدى المشغّل أصبحت في وضع الخمول لأن المستخدم أوقف الوسائط أو أوقفها مؤقتًا والبث انتهت المهلة.

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

يشير إلى ما إذا كان "مساعد Google" يستمع حاليًا أم لا.

سيُنشئ start() دائمًا ON_MUTED_CHANGED للإبلاغ عن القيمة الأولية.

المَعلمات:‫is_muted (bool): إذا كانت القيمة "صحيح"، يعني ذلك أنّ "مساعد Google" لا يستمع حاليًا لكلمة تفعيل الإجراء ولن يستجيب لطلبات المستخدم.
ON_NO_RESPONSE = 8

أكملت "مساعد Google" دورها بنجاح ولكن ليس لديها ما تقوله.

ON_RECOGNIZING_SPEECH_FINISHED = 5

حدّد "مساعد Google" العبارة التي تم التعرّف عليها أخيرًا.

المَعلمات:‫text (str): التفسير النهائي للنص لطلب بحث المستخدم
ON_RENDER_RESPONSE = 15

يشير هذا الرمز إلى أنّ "مساعد Google" لديه إخراج نصي لعرض الاستجابة.

المَعلمات:
  • type (RenderResponseType) – نوع الاستجابة المطلوب عرضها.
  • text (str) – السلسلة المطلوب عرضها لـ RenderResponseType.TEXT.
ON_RESPONDING_FINISHED = 7

انتهى "مساعد Google" من الاستجابة باستخدام الصوت.

ON_RESPONDING_STARTED = 6

يبدأ "مساعد Google" بالردّ صوتيًا.

سيستجيب "مساعد Google" إلى أن يتم تلقّي ON_RESPONDING_FINISHED .

المَعلمات:is_error_response (bool) – تشير "صحيح" إلى أنّه يتم تشغيل خطأ محلي عبر "تحويل النص إلى كلام" (TTS)، وإلا يستجيب المساعد باستجابة الخادم.
ON_START_FINISHED = 0

اكتمل بدء مكتبة "مساعد Google".

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, **_)

توسيع Event لإضافة تحليل response_type

class google.assistant.library.event.RenderResponseType

أنواع المحتوى المطلوب عرضها

مُستخدَم مع ON_RENDER_RESPONSE