Package google.assistant.embedded.v1alpha2

الفهرس

EmbeddedAssistant

خدمة تنفّذ Google Assistant API

تمريرة حاسمة

rpc Assist(AssistRequest) returns (AssistResponse)

بدء محادثة أو مواصلتها باستخدام "خدمة مساعد Google" المضمّنة. تُجري كل مكالمة جولة ذهاب وعودة واحدة، ويتم إرسال طلب صوتي إلى الخدمة وتلقّي الردّ الصوتي. تستخدم هذه الميزة البث ثنائي الاتجاه لتلقّي النتائج، مثل حدث END_OF_UTTERANCE، أثناء إرسال الصوت.

المحادثة هي عبارة عن اتصال واحد أو أكثر من اتصالات gRPC، يتكون كل منها من عدة طلبات وردود يتم بثها. على سبيل المثال، يسأل المستخدم إضافة إلى قائمة التسوّق، فيردّ "مساعد Google" على السؤال ماذا تريد أن تضيف؟. يمكن أن يكون تسلسل الطلبات والاستجابات التي يتم بثها في رسالة gRPC الأولى على النحو التالي:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.speech_results.transcript "إضافة إلى قائمة التسوق الخاصة بي"
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

يقول المستخدم بعد ذلك كعكة البيغل، ويردّ "مساعد Google" بعبارة حسنًا، لقد أضفت كعكة البيغل إلى قائمة التسوّق. يتم إرسال هذا الإجراء كطلب ربط آخر في gRPC إلى طريقة Assist، ومرة أخرى مع الطلبات والردود التي يتم بثها، مثل:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.dialog_state_out.microphone_mode.CLOSE_MICROPHONE
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

على الرغم من أنّ الترتيب الدقيق للردود غير مضمون، ستحتوي رسائل AssistResponse.audio_out المتسلسلة دائمًا على أجزاء متسلسلة من الصوت.

نطاقات الأذونات

يجب توفير نطاق OAuth التالي:

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

لمزيد من المعلومات، اطّلِع على دليل المصادقة.

AssistConfig

تحدِّد هذه السمة كيفية معالجة رسائل AssistRequest.

الحقول
audio_out_config

AudioOutConfig

مطلوبة لتحديد كيفية تنسيق المقطع الصوتي الذي سيتم عرضه.

screen_out_config

ScreenOutConfig

اختيارية: تحدِّد هذه السمة التنسيق المطلوب استخدامه عندما يعرض الخادم استجابة مرئية على الشاشة.

dialog_state_in

DialogStateIn

مطلوب يمثل حالة مربع الحوار الحالية.

device_config

DeviceConfig

إعدادات الجهاز التي تُعرِّف جهازًا معيّنًا بشكل فريد.

debug_config

DebugConfig

اختياري معلمات تصحيح الأخطاء لاستدعاء إجراء عن بُعد (RPC) لـ Assist بالكامل.

حقل الاتحاد type

يمكن أن تكون السمة "type" واحدة فقط مما يلي:
audio_in_config

AudioInConfig

تحدِّد هذه السياسة كيفية معالجة المقطع الصوتي الوارد التالي. هذه السمة مطلوبة في حال توفير AssistRequest.audio_in بايت في الطلبات اللاحقة.

text_query

string

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

AssistRequest

رسالة المستوى الأعلى التي أرسلها العميل. على العملاء إرسال رسالتَين على الأقل من رسائل AssistRequest، إضافةً إلى عدة رسائل. يجب أن تحتوي الرسالة الأولى على رسالة config وألا تحتوي على بيانات audio_in. يجب أن تحتوي جميع الرسائل اللاحقة على بيانات audio_in ويجب ألا تحتوي على رسالة config.

الحقول
حقل الاتحاد type يجب تحديد حقل واحد من هذه الحقول في كل AssistRequest. يمكن أن تكون السمة "type" واحدة فقط مما يلي:
config

AssistConfig

توفّر رسالة config معلومات إلى أداة التعرُّف تحدد كيفية معالجة الطلب. يجب أن تحتوي رسالة AssistRequest الأولى على رسالة config.

audio_in

bytes

البيانات الصوتية المطلوب التعرّف عليها يتم إرسال المقاطع الصوتية التسلسلية في رسائل AssistRequest تسلسلية. يجب ألا تحتوي رسالة AssistRequest الأولى على بيانات audio_in ويجب أن تحتوي جميع رسائل AssistRequest اللاحقة على بيانات audio_in. يجب ترميز وحدات بايت الصوت كما هو محدّد في AudioInConfig. يجب إرسال الصوت في الوقت الفعلي تقريبًا (16,000 عيّنة في الثانية). سيتم عرض خطأ إذا تم إرسال الصوت بشكل أسرع أو أبطأ بشكل ملحوظ.

AssistResponse

رسالة المستوى الأعلى التي يتلقّاها العميل. يتم بث سلسلة تتكون من رسالة AssistResponse واحدة أو أكثر إلى العميل.

الحقول
event_type

EventType

الإخراج فقط يشير إلى نوع الحدث.

audio_out

AudioOut

إخراج فقط: المقطع الصوتي الذي يتضمن رد "مساعد Google" على طلب البحث.

screen_out

ScreenOut

إخراج فقط يحتوي على استجابة "مساعد Google" المرئية لطلب البحث.

device_action

DeviceAction

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

speech_results[]

SpeechRecognitionResult

إخراج فقط تحتوي هذه القائمة المتكررة على قيمة صفرية أو أكثر من نتائج التعرف على الكلام التي تتطابق مع الأجزاء المتتالية من الصوت الذي تتم معالجته حاليًا، بدءًا من الجزء المقابل للصوت الأقدم (والجزء الأكثر ثباتًا) وحتى الجزء المقابل لآخر صوت. يمكن إنشاء تسلسل للسلاسل لعرض الاستجابة الكاملة قيد التقدم. عند اكتمال التعرف على الكلام، ستحتوي هذه القائمة على عنصر واحد مع stability من 1.0.

dialog_state_out

DialogStateOut

النتائج فقط: يحتوي على مخرجات ذات صلة بطلب بحث المستخدم.

debug_info

DebugInfo

النتائج فقط معلومات تصحيح الأخطاء لمطوّر البرامج لا يتم عرضه إلا إذا تم ضبط الطلب return_debug_info على "صحيح".

EventType

تشير هذه السمة إلى نوع الحدث.

عمليات التعداد
EVENT_TYPE_UNSPECIFIED لم يتم تحديد أي حدث.
END_OF_UTTERANCE يشير هذا الحدث إلى أنّ الخادم قد اكتشف نهاية الكلام المنطوق للمستخدم ولا يتوقع أي كلام إضافي. لذلك، لن يعالج الخادم الصوت الإضافي (مع أنه قد يعرض نتائج إضافية لاحقًا). على العميل إيقاف إرسال بيانات صوتية إضافية، وإغلاق اتصال gRPC بشكل نصفي، وانتظار أي نتائج إضافية إلى أن يغلق الخادم اتصال gRPC.

AudioInConfig

تُحدِّد كيفية معالجة بيانات audio_in التي سيتم تقديمها في الطلبات اللاحقة. للاطّلاع على الإعدادات المقترَحة، راجِع أفضل الممارسات لحزمة تطوير البرامج (SDK) لخدمة "مساعد Google".

الحقول
encoding

Encoding

مطلوب ترميز البيانات الصوتية المرسلة في جميع رسائل audio_in.

sample_rate_hertz

int32

مطلوب معدّل العينة (بالهيرتز) للبيانات الصوتية التي تم إرسالها في جميع رسائل audio_in. القيم الصالحة من 16000 إلى 24000، لكن الرقم 16000 هو الأمثل. للحصول على أفضل النتائج، اضبط معدّل أخذ العينات لمصدر الصوت على 16000 هرتز. وإذا لم يكن ذلك ممكنًا، استخدِم معدّل العيّنة الأصلي لمصدر الصوت (بدلاً من إعادة أخذ العيّنات).

الترميز

الترميز الصوتي للبيانات المُرسَلة في الرسالة الصوتية يجب أن يكون الصوت بقناة واحدة (أحادية).

عمليات التعداد
ENCODING_UNSPECIFIED غير محدَّد. ستعرض النتيجة google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 عينات صغيرة ذات علامة 16 بت غير مضغوطة (PCM الخطي). لا يتضمن هذا الترميز أي عنوان، بل يشمل وحدات بايت الصوت الأولية فقط.
FLAC FLAC (برنامج ترميز الصوت المجاني بدون فقدان البيانات) هو الترميز الموصى به لأنّه لا يؤدي إلى فقدان البيانات، وبالتالي لا يتم اختراق ميزة التعرّف على الصوت، ولا يتطلّب سوى نصف معدّل نقل البيانات لـ LINEAR16. يتضمّن هذا الترميز عنوان البث FLAC متبوعًا بالبيانات الصوتية. ويتيح هذا الإصدار استخدام نماذج 16 بت و24 بت، إلا أنّ بعض الحقول في STREAMINFO غير متوافقة.

AudioOut

الصوت الذي يتضمّن ردّ "مساعد Google" على الطلب يتم تلقّي مقاطع متسلسلة من البيانات الصوتية في رسائل AssistResponse تسلسلية.

الحقول
audio_data

bytes

إخراج فقط: البيانات الصوتية التي تحتوي على رد "مساعد Google" على طلب البحث يتم تلقّي مقاطع متسلسلة من البيانات الصوتية في رسائل AssistResponse تسلسلية.

AudioOutConfig

تحدِّد هذه السياسة التنسيق المطلوب الذي يستخدمه الخادم عند عرض رسائل audio_out.

الحقول
encoding

Encoding

مطلوب ترميز البيانات الصوتية التي سيتم عرضها في جميع رسائل audio_out.

sample_rate_hertz

int32

مطلوب يشير إلى معدّل العينة بالهرتز للبيانات الصوتية التي يتم عرضها في audio_out رسالة. القيم الصالحة هي: 16000-24000.

volume_percentage

int32

مطلوب الإعداد الحالي لمستوى الصوت لإخراج الصوت في الجهاز. تتراوح القيم الصالحة بين 1 و100 (ما يعادل 1% إلى 100%).

الترميز

الترميز الصوتي للبيانات المعروضة في الرسالة الصوتية. جميع الترميزات هي وحدات بايت للصوت غير معدَّل بدون عنوان، باستثناء ما هو موضّح أدناه.

عمليات التعداد
ENCODING_UNSPECIFIED غير محدَّد. ستعرض النتيجة google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 عينات صغيرة ذات علامة 16 بت غير مضغوطة (PCM الخطي).
MP3 ترميز الصوت MP3 يتم تشفير معدل العينة في الحمولة.
OPUS_IN_OGG ملف صوتي بترميز Opus ملفوف في حاوية بتنسيق ogg. وستكون النتيجة ملفًا يمكن تشغيله محليًا على Android وفي بعض المتصفحات (مثل Chrome). جودة الترميز أعلى بكثير من MP3 في حين تستخدم معدل نقل البيانات نفسه. يتم تشفير معدل العينة في الحمولة.

DebugConfig

تصحيح أخطاء الطلب الحالي

الحقول
return_debug_info

bool

وعند ضبط هذا الحقل على "صحيح"، قد تتم تعبئة الحقل debug_info في AssistResponse. ومع ذلك، سيؤدي ذلك إلى زيادة كبيرة في وقت استجابة الردود.

DebugInfo

معلومات تصحيح الأخطاء لمطوّر البرامج لا يتم عرضه إلا إذا تم ضبط الطلب return_debug_info على "صحيح".

الحقول
aog_agent_to_assistant_json

string

استجابة JSON الأصلية من وكيل Action-on-Google إلى خادم Google يُرجى الاطّلاع على AppResponse. لن تتم تعبئته إلا إذا كان صانع الطلب يملك مشروع AoG وكان مشروع AoG في وضع المعاينة.

DeviceAction

يتم عرض الاستجابة إلى الجهاز إذا شغّل المستخدم أحد إجراءات الجهاز. على سبيل المثال، سيتلقّى الجهاز الذي يتوافق مع طلب البحث Turn on thelight DeviceAction مع حمولة JSON تحتوي على دلالات الطلب.

الحقول
device_request_json

string

ملف JSON يحتوي على استجابة أوامر الجهاز التي تم إنشاؤها من قواعد إجراءات الجهاز التي تم تفعيلها، ويتم تحديد التنسيق من خلال هدف action.devices.EXECUTE لسمة معيّنة.

DeviceConfig

مطلوبة الحقول التي تتعرّف على الجهاز بالنسبة إلى "مساعد Google"

انظر أيضًا:

الحقول
device_id

string

المعرّف الفريد مطلوب للجهاز. يجب ألا يزيد طول المعرّف عن 128 حرفًا. على سبيل المثال: DBCDW098234. يجب أن يتطابق هذا المعرّف مع قيمة device_id التي تم إرجاعها من عملية تسجيل الجهاز. ويُستخدَم معرّف الجهاز هذا للمطابقة مع أجهزة المستخدم المسجَّلة للبحث عن سمات هذا الجهاز وإمكاناته المتوافقة. ومن المفترض ألّا تتغيّر هذه المعلومات على مستوى عمليات إعادة تشغيل الجهاز. ومع ذلك، يجب عدم حفظها من خلال عمليات إعادة الضبط على الإعدادات الأصلية.

device_model_id

string

المعرّف الفريد مطلوب لطراز الجهاز. ويجب أن يكون الجمع بين device_model_id وdevice_id مرتبطًا في السابق من خلال تسجيل الجهاز.

DeviceLocation

هناك ثلاثة مصادر للمواقع الجغرافية. يتم استخدامها مع هذه الأولوية:

  1. يتم استخدام DeviceLocation هذا بشكل أساسي للأجهزة الجوّالة المزوّدة بنظام تحديد المواقع العالمي (GPS).
  2. الموقع الذي يحدده المستخدم أثناء إعداد الجهاز؛ هذا لكل مستخدم على كل جهاز. ويتم استخدام هذا الموقع الجغرافي إذا لم يتم تحديد DeviceLocation.
  3. الموقع الجغرافي الذي تم استنتاجه استنادًا إلى عنوان IP. ولا يتم استخدام هذا إلا إذا لم يتم تحديد أيٍّ مما سبق.
الحقول
coordinates

LatLng

خط العرض وخط الطول للجهاز.

DialogStateIn

يوفّر هذا الخيار معلومات عن حالة مربّع الحوار الحالية.

الحقول
conversation_state

bytes

مطلوب يجب ضبط هذا الحقل دائمًا على قيمة DialogStateOut.conversation_state التي تم عرضها في متوسط عائد النقرة Assist السابق. ويجب حذفها فقط (لم يتم ضبط الحقل) في حال عدم توفّر استدعاء إجراء عن بُعد (RPC) Assist سابق، لأنّ هذا هو أول Assist استدعاء RPC يُجريه هذا الجهاز بعد ضبطه لأول مرة و/أو إعادة ضبطه على الإعدادات الأصلية.

language_code

string

مطلوبة لغة الطلب في بنية IETF BCP 47 (على سبيل المثال، "en-US"). يُرجى الاطّلاع على دعم اللغة للحصول على مزيد من المعلومات. إذا اخترت لغة لجهاز device_id هذا باستخدام قائمة الإعدادات في تطبيق "مساعد Google" على هاتفك، سيؤدي هذا الاختيار إلى إلغاء هذه القيمة.

device_location

DeviceLocation

اختياري: يشير إلى موقع الجهاز الذي نشأ منه طلب البحث.

is_new_conversation

bool

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

DialogStateOut

حالة مربّع الحوار الناتجة عن طلب بحث المستخدم قد يتم تلقّي العديد من هذه الرسائل.

الحقول
supplemental_display_text

string

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

conversation_state

bytes

معلومات الحالة للإخراج فقط لاستدعاء الإجراء عن بُعد لـ Assist التالي يجب حفظ هذه القيمة في البرنامج وعرضها في الحقل DialogStateIn.conversation_state مع متوسط عائد النقرة التالي بقيمة Assist. (لا يحتاج العميل إلى تفسير هذه القيمة أو استخدامها بأي طريقة أخرى.) ويجب حفظ هذه المعلومات في كل عمليات إعادة تشغيل الجهاز. ومع ذلك، يجب محو هذه القيمة (لا يتم حفظها في البرنامج) أثناء إعادة الضبط على الإعدادات الأصلية.

microphone_mode

MicrophoneMode

الإخراج فقط: تحدّد هذه السمة وضع الميكروفون بعد معالجة متوسط عائد النقرة Assist هذا.

volume_percentage

int32

إخراج فقط تم تحديث مستوى الصوت. ستكون القيمة 0 أو سيتم إسقاطها (مع الإشارة إلى عدم حدوث أي تغيير) ما لم يتم التعرّف على طلب صوتي، مثل رفع مستوى الصوت أو ضبط مستوى الصوت 4، وفي هذه الحالة ستكون القيمة بين 1 و100 (يتوافق مع مستوى الصوت الجديد بين 1% و100%). عادةً ما يستخدم العميل مستوى الصوت هذا عند تشغيل بيانات audio_out، ويحتفظ بهذه القيمة بصفته مستوى الصوت الحالي ويضيفها في AudioOutConfig من AssistRequest التالية. (قد تنفِّذ بعض البرامج أيضًا طرقًا أخرى للسماح بتغيير مستوى الصوت الحالي، على سبيل المثال، من خلال توفير شريط تمرير يمكن للمستخدم تدويره).

MicrophoneMode

الحالات المحتملة للميكروفون بعد اكتمال Assist RPC.

عمليات التعداد
MICROPHONE_MODE_UNSPECIFIED لم يتم تحديد أي وضع.
CLOSE_MICROPHONE لا تتوقّع الخدمة سؤال متابعة من المستخدم. يجب أن يبقى الميكروفون متوقفًا إلى أن يُعيد المستخدم تفعيله.
DIALOG_FOLLOW_ON تتوقّع الخدمة سؤال متابعة من المستخدم. يجب إعادة فتح الميكروفون عند اكتمال تشغيل AudioOut (عن طريق بدء مكالمة Assist جديدة حول RPC لإرسال الصوت الجديد).

ScreenOut

استجابة "مساعد Google" المرئية لطلب البحث تم التفعيل من قِبل "screen_out_config".

الحقول
format

Format

الإخراج فقط: تنسيق بيانات الشاشة المقدَّمة

data

bytes

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

التنسيق

التنسيقات المحتملة لبيانات الشاشة.

عمليات التعداد
FORMAT_UNSPECIFIED لم يتم تحديد أي تنسيق.
HTML ستحتوي البيانات على تنسيق HTML5 كامل التنسيق تم ترميزه بترميز UTF-8، مثل <html><body><div>...</div></body></html>. ويجب أن يتم عرضه مع الاستجابة الصوتية. لاحظ أنه يجب تضمين HTML5 DOCTYPE في بيانات HTML الفعلية.

ScreenOutConfig

تحدِّد هذه السياسة التنسيق المطلوب الذي يستخدمه الخادم عند عرض استجابة screen_out.

الحقول
screen_mode

ScreenMode

وضع الشاشة المرئي الحالي للجهاز أثناء إصدار طلب البحث

ScreenMode

الأوضاع الممكنة لإخراج الشاشة المرئي على الجهاز.

عمليات التعداد
SCREEN_MODE_UNSPECIFIED لم يتم تحديد أي وضع للفيديو. قد يستجيب "مساعد Google" كما لو كان في وضع OFF.
OFF الشاشة مطفأة (أو تم ضبط درجة السطوع أو إعدادات أخرى على درجة منخفضة جدًا لدرجة لا يمكن رؤيتها). لن يعرض "مساعد Google" عادةً استجابة من الشاشة في هذا الوضع.
PLAYING سيعرض "مساعد Google" عادةً استجابة جزئية للشاشة في هذا الوضع.

SpeechRecognitionResult

النص المقدَّر للعبارة التي قالها المستخدم. قد يكون ذلك مقطعًا واحدًا أو التخمين الكامل لطلب البحث الشفهي للمستخدم.

الحقول
transcript

string

للإخراج فقط نص النص الذي يمثل الكلمات التي قالها المستخدم.

stability

float

الإخراج فقط: تقدير لاحتمالية عدم تغيير "مساعد Google" لتخمينه بشأن هذه النتيجة. تتراوح القيم من 0.0 (غير مستقر تمامًا) إلى 1.0 (ثابتة ونهائية تمامًا). القيمة التلقائية 0.0 هي قيمة مُرسَلة تشير إلى أنّه لم يتم ضبط stability.