دمج "مساعد Google" في مشروعك (بلغات أخرى)

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

عمليات ربط gRPC

تم إنشاء "خدمة مساعد Google" استنادًا إلى gRPC، وهي إطار عمل مفتوح المصدر وعالية الأداء لاستدعاء الإجراء عن بُعد (RPC). يُعد إطار العمل هذا مناسبًا تمامًا للبث الصوتي ثنائي الاتجاه.

Python

إذا كنت تستخدم Python، فابدأ باستخدام هذا الدليل.

C++

ألقِ نظرة على نموذج C++ على GitHub.

Node.js

يمكنك إلقاء نظرة على نموذج Node.js على GitHub.

Android Things

هل يهمّك الأجهزة المضمّنة؟ يمكنك الاطّلاع على نموذج Assistant SDK for Android Things.

اللغات الأخرى

• استنسِخ مستودع googleapis للحصول على تعريفات واجهة مخزن البروتوكول المؤقت لواجهة Google Assistant Service API.
• اتّبِع مستندات gRPC لإنشاء عمليات ربط gRPC للغتك التي تختارها.
• اتّبِع الخطوات الواردة في الأقسام أدناه.

يجب المصادقة على حسابك على Google والمصادقة عليه للعمل مع "مساعد Google"

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

الحصول على رموز OAuth المميزة باستخدام نطاق حزمة تطوير البرامج (SDK) لخدمة "مساعد Google"

تستخدم حزمة تطوير البرامج (SDK) لخدمة "مساعد Google" رموز الدخول عبر OAuth 2.0 للسماح لجهازك بالاتصال بخدمة "مساعد Google".

عند إنشاء نماذج أولية، يمكنك استخدام أداة التفويض لإنشاء بيانات اعتماد OAuth2.0 بسهولة من ملف client_secret_<client-id>.json الذي تم إنشاؤه عند تسجيل طراز جهازك.

قم بما يلي لإنشاء بيانات الاعتماد:

1. استخدام بيئة Python الافتراضية لعزل أداة التفويض وتبعياتها عن حزم Python للنظام.

   sudo apt-get update
   sudo apt-get install python3-dev python3-venv # Use python3.4-venv if the package cannot be found.
   python3 -m venv env
   env/bin/python -m pip install --upgrade pip setuptools wheel
   source env/bin/activate
   

2. ثبِّت أداة التفويض:

   python -m pip install --upgrade google-auth-oauthlib[tool]

3. شغِّل الأداة. أزِل علامة --headless إذا كنت تشغِّل هذا من وحدة طرفية على الجهاز (وليس جلسة بروتوكول النقل الآمن):

   google-oauthlib-tool --client-secrets /path/to/client_secret_client-id.json --scope https://www.googleapis.com/auth/assistant-sdk-prototype --save --headless
   

عندما تكون مستعدًا لدمج التفويض كجزء من آلية توفير المتطلبات اللازمة لجهازك، يمكنك الاطّلاع على أدلة استخدام OAuth 2.0 للوصول إلى Google APIs لفهم كيفية الحصول على رموز الدخول عبر بروتوكول OAuth والاحتفاظ بها واستخدامها للسماح لجهازك باستخدام واجهة برمجة التطبيقات Assistant API.

يُرجى استخدام ما يلي أثناء الاطّلاع على هذه الأدلة:

• نطاق OAuth: https://www.googleapis.com/auth/assistant-sdk-prototype

• مسارات OAuth المتوافقة:

  • (مقترَح) التطبيقات المثبّتة
  • تطبيقات خادم الويب
  ملاحظة: إنّ التدفق المحدود لجهاز الإدخال غير متاح.

يُرجى الاطّلاع على أفضل الممارسات بشأن الخصوصية والأمان للحصول على اقتراحات حول كيفية تأمين جهازك.

مصادقة اتصال gRPC باستخدام رموز OAuth المميزة

أخيرًا، اجمع كل المعلومات معًا من خلال قراءة كيفية استخدام المصادقة المستندة إلى الرمز المميّز مع Google لمصادقة اتصال gRPC بواجهة Assistant API.

تسجيل جهازك

ويمكنك تسجيل طراز جهازك ومثيله إما يدويًا أو باستخدام أداة التسجيل (المتوفرة في بايثون).

تنفيذ مربّع حوار أساسي للمحادثة مع "مساعد Google"

1. تنفيذ برنامج gRPC للبث ثنائي الاتجاه لواجهة برمجة التطبيقات لخدمة مساعد Google
2. انتظر حتى يبدأ المستخدم طلبًا جديدًا (على سبيل المثال، انتظر حتى مقاطعة GPIO عند الضغط على زر).

3. أرسِل رسالة AssistRequest مع مجموعة حقول config (راجِع AssistConfig). تأكَّد من أنّ الحقل config يحتوي على ما يلي:

   • الحقل audio_in_config الذي يحدد كيفية معالجة بيانات audio_in التي سيتم تقديمها في الطلبات اللاحقة (راجِع AudioInConfig).
   • الحقل audio_out_config، وهو يحدد التنسيق المطلوب لكي يستخدمه الخادم عند عرض رسائل audio_out (راجِع AudioOutConfig).
   • الحقل device_config الذي يحدّد الجهاز المسجّل في "مساعد Google" (راجِع DeviceConfig).
   • الحقل dialog_state_in الذي يحتوي على language_code المرتبط بالطلب (راجِع DialogStateIn).

4. ابدأ التسجيل.

5. أرسِل عدة رسائل AssistRequest صادرة مع بيانات صوتية من الطلب المنطوق في حقل audio_in.

6. تعامل مع رسائل AssistResponse الواردة.

7. استخرِج البيانات الوصفية للمحادثة من رسالة AssistResponse. على سبيل المثال، من dialog_state_out، احصل على conversation_state وvolume_percentage (راجِع DialogStateOut).

8. يمكنك إيقاف التسجيل عند تلقّي AssistResponse مع event_type من END_OF_UTTERANCE.

9. تشغيل الصوت من إجابة "مساعد Google" باستخدام بيانات صوتية من الحقل audio_out.

10. خُذ conversation_state التي استخرجتها سابقًا وانسخها في رسالة DialogStateIn في AssistConfig ضِمن AssistRequest التالي.

بهذه الطريقة، تكون جاهزًا لتقديم طلباتك الأولى إلى "مساعد Google" عبر جهازك.

تمديد مربّع حوار محادثة باستخدام "إجراءات الجهاز"

قم بتوسيع مربع حوار المحادثة الأساسية أعلاه لتشغيل الإمكانات الفريدة للأجهزة لجهازك المحدد:

1. في رسائل AssistResponse الواردة، استخرِج حقل device_action (راجِع DeviceAction).
2. تحليل حمولة JSON للحقل device_request_json يُرجى الرجوع إلى صفحة سمات الجهاز للاطّلاع على قائمة السمات المتوافقة. تعرض كل صفحة في مخطط السمات نموذج طلب تنفيذي يتضمن أوامر الجهاز والمعلَمات التي يتم عرضها في حمولة JSON.

الحصول على نص طلب المستخدم

إذا كانت لديك شاشة عرض مرتبطة بالجهاز، فقد ترغب في استخدامها لعرض طلب المستخدم. للحصول على هذا النص، حلّل الحقل speech_results في رسائل AssistResponse. عند اكتمال التعرّف على الكلام، ستحتوي هذه القائمة على عنصر واحد مع ضبط stability على 1.0.

الاطّلاع على النص و/أو العرض المرئي لردّ "مساعد Google"

إذا كان هناك شاشة متصلة بالجهاز، يمكنك استخدامها لعرض ردّ "مساعد Google" بتنسيق النص العادي على طلب المستخدم. يوجد هذا النص في الحقل DialogStateOut.supplemental_display_text.

يتيح "مساعد Google" ردودًا مرئية عبر HTML5 لطلبات بحث معيّنة (ما حالة الطقس في ماونتن فيو؟ أو ما الوقت؟). لتفعيل هذا الإعداد، عليك ضبط الحقل screen_out_config في AssistConfig. تحتوي رسالة ScreenOutConfig على الحقل screen_mode الذي يجب ضبطه على PLAYING.

سيتم بعد ذلك ضبط الحقل screen_out على رسائل AssistResponse. يمكنك استخراج بيانات HTML5 (إذا كانت متوفّرة) من الحقل data.

إرسال الطلبات عبر إدخال النص

إذا كانت لديك واجهة نصية (مثل لوحة مفاتيح) متصلة بالجهاز، اضبط الحقل text_query في حقل config (راجِع AssistConfig). ولا تضبط الحقل audio_in_config.

تحديد المشاكل وحلّها

راجِع صفحة تحديد المشاكل وحلّها إذا واجهت مشاكل.