تم إيقاف إجراءات المحادثات نهائيًا في 13 حزيران (يونيو) 2023. لمزيد من المعلومات، يُرجى الاطّلاع على إنهاء إجراءات المحادثة.

تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

Package google.assistant.embedded.v1alpha1

الفهرس

EmbeddedAssistant (واجهة)
AudioInConfig (رسالة)
AudioInConfig.Encoding (تعداد)
AudioOut (رسالة)
AudioOutConfig (رسالة)
AudioOutConfig.Encoding (تعداد)
ConverseConfig (رسالة)
ConverseRequest (رسالة)
ConverseResponse (رسالة)
ConverseResponse.EventType (تعداد)
ConverseResult (رسالة)
ConverseResult.MicrophoneMode (تعداد)
ConverseState (رسالة)

EmbeddedAssistant

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

Converse

Converse
`rpc Converse(ConverseRequest) returns (ConverseResponse)` بدء محادثة أو متابعتها باستخدام خدمة المساعد المضمّنة. تُجري كل مكالمة جولة ذهاب وعودة واحدة، ويتم إرسال طلب صوتي إلى الخدمة وتلقّي الردّ الصوتي. تستخدم هذه الميزة البث ثنائي الاتجاه لتلقّي النتائج، مثل حدث `END_OF_UTTERANCE`، أثناء إرسال الصوت. المحادثة هي عبارة عن اتصال واحد أو أكثر من اتصالات gRPC، يتكون كل منها من عدة طلبات وردود يتم بثها. مثلاً، يسأل المستخدم إضافة إلى قائمة التسوّق، فيردّ المساعد بعبارة ماذا تريد أن تضيف؟. يمكن أن يكون تسلسل الطلبات والاستجابات التي يتم بثها في رسالة gRPC الأولى على النحو التالي: ConverseRequest.config ConverseRequest.audio_in ConverseRequest.audio_in ConverseRequest.audio_in ConverseRequest.audio_in ConverseResponse.event_type.END_OF_UTTERANCE ConverseResponse.result.microphone_mode.DIALOG_FOLLOW_ON ConverseResponse.audio_out ConverseResponse.audio_out ConverseResponse.audio_out بعد ذلك، يقول المستخدم كعكة البيغل ويردّ عليه المساعد بعبارة حسنًا، لقد أضفت كعكة البيغل إلى قائمة التسوّق. يتم إرسال هذا الإجراء كطلب ربط آخر في gRPC إلى طريقة `Converse`، ومرة أخرى مع الطلبات والردود التي يتم بثها، مثل: ConverseRequest.config ConverseRequest.audio_in ConverseRequest.audio_in ConverseRequest.audio_in ConverseResponse.event_type.END_OF_UTTERANCE ConverseResponse.result.microphone_mode.CLOSE_MICROPHONE ConverseResponse.audio_out ConverseResponse.audio_out ConverseResponse.audio_out ConverseResponse.audio_out وبالرغم من أن الترتيب الدقيق للردود غير مضمون، فإن رسائل ConverseResponse.audio_out المتسلسلة ستحتوي دائمًا على أجزاء متسلسلة من الصوت. التفويض يجب توفير نطاق OAuth التالي: `https://www.googleapis.com/auth/assistant-sdk-prototype` لمزيد من المعلومات، اطّلِع على دليل المصادقة.

rpc Converse(ConverseRequest) returns (ConverseResponse)

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

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

ConverseRequest.config
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseResponse.event_type.END_OF_UTTERANCE
ConverseResponse.result.microphone_mode.DIALOG_FOLLOW_ON
ConverseResponse.audio_out
ConverseResponse.audio_out
ConverseResponse.audio_out

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

ConverseRequest.config
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseRequest.audio_in
ConverseResponse.event_type.END_OF_UTTERANCE
ConverseResponse.result.microphone_mode.CLOSE_MICROPHONE
ConverseResponse.audio_out
ConverseResponse.audio_out
ConverseResponse.audio_out
ConverseResponse.audio_out

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

التفويض

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

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

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

AudioInConfig

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

الحقول

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

encoding

Encoding

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

sample_rate_hertz

int32

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

الترميز

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

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

AudioOut

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

الحقول

الحقول
`audio_data`	`bytes` إخراج فقط: البيانات الصوتية التي تحتوي على رد المساعد على طلب البحث. يتم تلقّي مقاطع متسلسلة من البيانات الصوتية في رسائل `ConverseResponse` تسلسلية.

audio_data

bytes

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

AudioOutConfig

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

الحقول

الحقول
`encoding`	`Encoding` مطلوب ترميز البيانات الصوتية التي سيتم عرضها في جميع رسائل `audio_out`.
`sample_rate_hertz`	`int32` مطلوب يشير إلى معدّل العينة بالهرتز للبيانات الصوتية التي يتم عرضها في `audio_out` رسالة. القيم الصالحة هي: 16000-24000.
`volume_percentage`	`int32` مطلوب الإعداد الحالي لمستوى الصوت لإخراج الصوت في الجهاز. تتراوح القيم الصالحة بين 1 و100 (ما يعادل 1% إلى 100%).

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 في حين تستخدم معدل نقل البيانات نفسه. يتم تشفير معدل العينة في الحمولة.

ConverseConfig

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

الحقول

الحقول
`audio_in_config`	`AudioInConfig` مطلوبة: تحدّد هذه السمة كيفية معالجة المقطع الصوتي الوارد التالي.
`audio_out_config`	`AudioOutConfig` مطلوبة لتحديد كيفية تنسيق المقطع الصوتي الذي سيتم عرضه.
`converse_state`	`ConverseState` مطلوب يمثل حالة مربع الحوار الحالية.

audio_in_config

AudioInConfig

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

audio_out_config

AudioOutConfig

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

converse_state

ConverseState

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

ConverseRequest

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

الحقول

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

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

config

ConverseConfig

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

audio_in

bytes

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

ConverseResponse

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

الحقول
حقل الاتحاد `converse_response` ستتم تعبئة حقل واحد فقط من هذه الحقول في كل `ConverseResponse`. يمكن أن تكون السمة "`converse_response`" واحدة فقط مما يلي:
`error`	`Status` الإخراج فقط في حال تعيينها، سيتم عرض رسالة `google.rpc.Status` التي تحدد الخطأ في العملية. وفي حال حدوث خطأ أثناء المعالجة، سيتم ضبط هذه الرسالة ولن يتم إرسال أي رسائل أخرى.
`event_type`	`EventType` الإخراج فقط يشير إلى نوع الحدث.
`audio_out`	`AudioOut` إخراج فقط الصوت الذي يتضمن رد المساعد على طلب البحث.
`result`	`ConverseResult` الإخراج فقط: هي النتيجة الدلالية لطلب البحث الشفهي الذي أدخله المستخدم.

EventType

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

عمليات التعداد

EVENT_TYPE_UNSPECIFIED لم يتم تحديد أي حدث.

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

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

ConverseResult

النتيجة الدلالية لطلب البحث الشفهي للمستخدم.

الحقول
`spoken_request_text`	`string` الإخراج فقط: النسخة المتوافقة مع عبارة المستخدم التي قالها المستخدم.
`spoken_response_text`	`string` الإخراج فقط: نص الرد الشفهي للمساعد. ولا يظهر هذا الخيار إلا عند تنفيذ إجراء IFTTT.
`conversation_state`	`bytes` معلومات الحالة للإخراج فقط بشأن `ConverseRequest` اللاحقة يجب حفظ هذه القيمة في البرنامج وعرضها في `conversation_state` مع `ConverseRequest` التالية. (لا يحتاج العميل إلى تفسير هذه القيمة أو استخدامها بأي طريقة أخرى.) ليست هناك حاجة لحفظ هذه المعلومات عبر عمليات إعادة تشغيل الجهاز.
`microphone_mode`	`MicrophoneMode` الإخراج فقط: تحدّد هذه السمة وضع الميكروفون بعد معالجة متوسط عائد النقرة `Converse` هذا.
`volume_percentage`	`int32` إخراج فقط تم تحديث مستوى الصوت. ستكون القيمة 0 أو سيتم حذفها (مع الإشارة إلى عدم حدوث أي تغيير) ما لم يتم التعرّف على طلب صوتي، مثل "رفع مستوى الصوت" أو "ضبط مستوى الصوت على 4"، وفي هذه الحالة ستكون القيمة بين 1 و100 (يتوافق مع مستوى الصوت الجديد بين 1% و100%). عادةً ما يستخدم العميل مستوى الصوت هذا عند تشغيل بيانات `audio_out`، ويحتفظ بهذه القيمة بصفته مستوى الصوت الحالي ويضيفها في `AudioOutConfig` من `ConverseRequest` التالية. (قد تنفِّذ بعض البرامج أيضًا طرقًا أخرى للسماح بتغيير مستوى الصوت الحالي، على سبيل المثال، من خلال توفير شريط تمرير يمكن للمستخدم تدويره).

MicrophoneMode

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

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

ConverseState

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

الحقول

الحقول
`conversation_state`	`bytes` مطلوب يشير إلى قيمة `conversation_state` التي تم عرضها في `ConverseResponse` السابقة. احذف (لا تضبط الحقل) إذا لم يكن هناك `ConverseResponse` سابق. في حال توفُّر `ConverseResponse` سابقًا، يُرجى عدم حذف هذا الحقل، لأنّ ذلك سيؤدي إلى إنهاء تلك المحادثة (وسيؤدّي هذا الطلب الجديد إلى بدء محادثة جديدة).

conversation_state

bytes

مطلوب يشير إلى قيمة conversation_state التي تم عرضها في ConverseResponse السابقة. احذف (لا تضبط الحقل) إذا لم يكن هناك ConverseResponse سابق. في حال توفُّر ConverseResponse سابقًا، يُرجى عدم حذف هذا الحقل، لأنّ ذلك سيؤدي إلى إنهاء تلك المحادثة (وسيؤدّي هذا الطلب الجديد إلى بدء محادثة جديدة).