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): بيانات اعتماد العميل OAuth2 من Google
  • ‫device_model_id (str): معرّف device_model_id الذي تم تسجيله لمشروعك على Google. يجب ألا تكون هذه السلسلة فارغة.
الزيادة:

ValueError – إذا تم ترك device_model_id على القيمة "بدون" أو فارغة
device_id

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

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

المرتجعات:رقم تعريف الجهاز بعد start() تمّت jego
نوع القيمة التي يتم عرضها:str
send_text_query(طلب بحث)

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

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

المَعلمات:‫طلب البحث (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, **_)

يُوسّع نطاق الحدث لإضافة تحليل "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)

توسيع Event لإضافة سمة "actions"

actions

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

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

حدث أنشأه "مساعد Google"

type

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

args

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

static New(event_type, args, **kwargs)

أنشئ حدثًا جديدًا باستخدام فئة حدث متخصّصة عند الحاجة.

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