Package google.assistant.embedded.v1alpha2

فهرست مطالب

EmbeddedAssistant

سرویسی که Google Assistant API را پیاده سازی می کند.

کمک کنید

rpc Assist( AssistRequest ) returns ( AssistResponse )

مکالمه را با سرویس دستیار تعبیه شده آغاز می کند یا ادامه می دهد. هر تماس یک رفت و برگشت انجام می دهد، یک درخواست صوتی به سرویس ارسال می کند و پاسخ صوتی را دریافت می کند. از جریان دو طرفه برای دریافت نتایج، مانند رویداد END_OF_UTTERANCE ، هنگام ارسال صدا استفاده می کند.

مکالمه یک یا چند اتصال gRPC است که هر کدام از چندین درخواست و پاسخ جریانی تشکیل شده است. به عنوان مثال، کاربر می گوید Add to my shopping list و دستیار پاسخ می دهد چه چیزی را می خواهید اضافه کنید؟ . دنباله درخواست ها و پاسخ های جاری در اولین پیام 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

سپس کاربر می گوید bagels و دستیار پاسخ می دهد OK، من شیرینی ها را به لیست خرید شما اضافه کرده ام . این به عنوان یک تماس دیگر اتصال 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

برای اطلاعات بیشتر، به راهنمای Auth مراجعه کنید.

AssistConfig

نحوه پردازش پیام های AssistRequest مشخص می کند.

زمینه های
audio_out_config

AudioOutConfig

Required نحوه فرمت کردن صدایی که برگردانده می شود را مشخص می کند.

screen_out_config

ScreenOutConfig

اختیاری فرمت مورد نظر را برای استفاده در زمانی که سرور یک پاسخ صفحه نمایش بصری برمی گرداند را مشخص می کند.

dialog_state_in

DialogStateIn

Required نشان دهنده وضعیت گفتگوی فعلی است.

device_config

DeviceConfig

پیکربندی دستگاه که به طور منحصر به فرد یک دستگاه خاص را شناسایی می کند.

debug_config

DebugConfig

پارامترهای دیباگ اختیاری برای کل Assist RPC.

type فیلد اتحادیه

type می تواند تنها یکی از موارد زیر باشد:

audio_in_config

AudioInConfig

نحوه پردازش صدای ورودی بعدی را مشخص می کند. اگر بایت‌های AssistRequest.audio_in در درخواست‌های بعدی ارائه شوند، ضروری است.

text_query

string

ورودی نوشتاری برای ارسال به دستیار. اگر ورودی صوتی در دسترس نباشد، می‌توان آن را از یک رابط متنی پر کرد.

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 مشخص شده است کدگذاری شوند. صدا باید تقریباً در زمان واقعی (16000 نمونه در ثانیه) ارسال شود. اگر صدا به میزان قابل توجهی سریعتر یا کندتر ارسال شود، یک خطا برگردانده می شود.

AssistResponse

پیام سطح بالای دریافت شده توسط مشتری. مجموعه ای از یک یا چند پیام AssistResponse به مشتری ارسال می شود.

زمینه های
event_type

EventType

Output-only نوع رویداد را نشان می دهد.

audio_out

AudioOut

فقط خروجی صدای حاوی پاسخ دستیار به درخواست.

screen_out

ScreenOut

Output-only شامل پاسخ بصری دستیار به درخواست است.

device_action

DeviceAction

Output-only شامل اقدامی است که توسط پرس و جو با بارهای مناسب و تجزیه معنایی ایجاد می شود.

speech_results[]

SpeechRecognitionResult

فقط خروجی این لیست مکرر حاوی صفر یا بیشتر نتایج تشخیص گفتار است که مربوط به بخش های متوالی صدایی است که در حال حاضر پردازش می شود، از قسمت مربوط به اولین صدا (و پایدارترین بخش) شروع می شود تا قسمت مربوط به جدیدترین صدا. رشته ها را می توان برای مشاهده پاسخ در حال پیشرفت کامل به هم متصل کرد. هنگامی که تشخیص گفتار کامل شد، این لیست حاوی یک مورد با stability 1.0 خواهد بود.

dialog_state_out

DialogStateOut

Output-only شامل خروجی مربوط به درخواست کاربر است.

debug_info

DebugInfo

اطلاعات اشکال‌زدایی فقط خروجی برای برنامه‌نویس. فقط در صورتی برگردانده می شود که درخواست return_debug_info روی true تنظیم کند.

نوع رویداد

نوع رویداد را نشان می دهد.

Enums
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 هرتز تنظیم کنید. اگر این امکان پذیر نیست، از نرخ نمونه بومی منبع صوتی استفاده کنید (به جای نمونه برداری مجدد).

رمزگذاری

رمزگذاری صوتی داده های ارسال شده در پیام صوتی. صدا باید تک کاناله (مونو) باشد.

Enums
ENCODING_UNSPECIFIED مشخص نشده است. نتیجه google.rpc.Code.INVALID_ARGUMENT را برمی گرداند.
LINEAR16 نمونه‌های 16 بیتی امضا نشده فشرده نشده (PCM خطی). این رمزگذاری شامل هدر نیست، فقط بایت های صوتی خام را شامل می شود.
FLAC FLAC (Free Lossless Audio Codec) رمزگذاری توصیه شده است زیرا بدون تلفات است - بنابراین تشخیص به خطر نمی افتد - و فقط به نیمی از پهنای باند LINEAR16 نیاز دارد. این رمزگذاری شامل هدر جریان FLAC به دنبال داده های صوتی است. از نمونه های 16 بیتی و 24 بیتی پشتیبانی می کند، با این حال، همه فیلدها در STREAMINFO پشتیبانی نمی شوند.

خروجی صدا

صوتی حاوی پاسخ دستیار به درخواست. تکه های متوالی داده های صوتی در پیام های متوالی AssistResponse دریافت می شوند.

زمینه های
audio_data

bytes

فقط خروجی داده های صوتی حاوی پاسخ دستیار به درخواست. تکه های متوالی داده های صوتی در پیام های متوالی AssistResponse دریافت می شوند.

AudioOutConfig

فرمت مورد نظر را مشخص می کند تا سرور هنگام بازگرداندن پیام های audio_out از آن استفاده کند.

زمینه های
encoding

Encoding

مورد نیاز رمزگذاری داده های صوتی باید در همه پیام های audio_out برگردانده شود.

sample_rate_hertz

int32

مورد نیاز نرخ نمونه بر حسب هرتز از داده های صوتی بازگردانده شده در پیام های audio_out . مقادیر معتبر عبارتند از: 16000-24000.

volume_percentage

int32

مورد نیاز تنظیم حجم فعلی خروجی صدای دستگاه. مقادیر معتبر 1 تا 100 (مرتبط با 1٪ تا 100٪) است.

رمزگذاری

رمزگذاری صوتی داده های بازگردانده شده در پیام صوتی. همه رمزگذاری ها بایت های صوتی خام و بدون سرصفحه هستند، به جز موارد زیر.

Enums
ENCODING_UNSPECIFIED مشخص نشده است. نتیجه google.rpc.Code.INVALID_ARGUMENT را برمی گرداند.
LINEAR16 نمونه‌های 16 بیتی امضا نشده فشرده نشده (PCM خطی).
MP3 رمزگذاری صوتی MP3 نرخ نمونه در محموله رمزگذاری شده است.
OPUS_IN_OGG صدای رمزگذاری شده با Opus که در یک ظرف Ogg پیچیده شده است. نتیجه فایلی خواهد بود که می تواند به صورت بومی در اندروید و در برخی از مرورگرها (مانند کروم) پخش شود. کیفیت رمزگذاری به طور قابل توجهی بالاتر از MP3 است در حالی که از همان میزان بیت استفاده می شود. نرخ نمونه در محموله رمزگذاری شده است.

DebugConfig

اشکال زدایی پارامترهای درخواست فعلی

زمینه های
return_debug_info

bool

وقتی این فیلد روی true تنظیم شود، قسمت debug_info در AssistResponse ممکن است پر شود. با این حال تاخیر پاسخ ها را به طور قابل توجهی افزایش می دهد.

DebugInfo

اطلاعات اشکال زدایی برای توسعه دهنده فقط در صورتی برگردانده می شود که درخواست return_debug_info روی true تنظیم کند.

زمینه های
aog_agent_to_assistant_json

string

پاسخ JSON اصلی از یک عامل Action-on-Google به سرور Google. AppResponse را ببینید. فقط در صورتی پر می شود که درخواست کننده پروژه AoG را داشته باشد و پروژه AoG در حالت پیش نمایش باشد.

DeviceAction

اگر کاربر یک Device Action را راه‌اندازی کرده باشد، پاسخ به دستگاه برمی‌گردد. برای مثال، دستگاهی که از عبارت Turn on the light پشتیبانی می‌کند، یک DeviceAction با یک بار JSON دریافت می‌کند که حاوی معنای درخواست است.

زمینه های
device_request_json

string

JSON حاوی پاسخ فرمان دستگاه است که از گرامر فعال شده Device Action ایجاد شده است. قالب با هدف action.devices.EXECUTE برای یک ویژگی مشخص داده شده است.

DeviceConfig

فیلدهای مورد نیاز که دستگاه را به دستیار شناسایی می کند.

همچنین ببینید:

زمینه های
device_id

string

شناسه منحصر به فرد مورد نیاز برای دستگاه. طول شناسه باید 128 کاراکتر یا کمتر باشد. مثال: DBCDW098234. این باید با device_id که از ثبت دستگاه برگردانده شده است مطابقت داشته باشد. این 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 RPC قبلی وجود نداشته باشد، باید حذف شود (فیلد تنظیم نشده است)، زیرا این اولین 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

فقط خروجی متن نمایش تکمیلی از دستیار. این می تواند مانند سخنرانی در AssistResponse.audio_out باشد یا می تواند اطلاعات اضافی باشد که به درک کاربر کمک می کند.

conversation_state

bytes

اطلاعات حالت فقط خروجی برای Assist RPC بعدی. این مقدار باید در کلاینت ذخیره شود و در قسمت DialogStateIn.conversation_state با Assist RPC بعدی برگردانده شود. (کاربر نیازی به تفسیر یا استفاده از این مقدار ندارد.) این اطلاعات باید در راه اندازی مجدد دستگاه ذخیره شود. با این حال، این مقدار باید در طول بازنشانی به‌طور پیش‌فرض کارخانه پاک شود (در کلاینت ذخیره نشود).

microphone_mode

MicrophoneMode

Output-only حالت میکروفون را پس از پردازش این Assist RPC مشخص می کند.

volume_percentage

int32

سطح صدا فقط خروجی به روز شده است. مقدار 0 خواهد بود یا حذف می شود (نشان دهنده عدم تغییر) مگر اینکه یک فرمان صوتی مانند افزایش صدا یا تنظیم سطح صدا 4 تشخیص داده شود، در این صورت مقدار بین 1 تا 100 خواهد بود (مطابق با سطح صدای جدید 1٪). تا 100 درصد. به طور معمول، یک کلاینت باید از این سطح صدا هنگام پخش داده های audio_out استفاده کند و این مقدار را به عنوان سطح صدای فعلی حفظ کند و آن را در AudioOutConfig از AssistRequest بعدی عرضه کند. (برخی از مشتریان همچنین ممکن است راه های دیگری را برای اجازه دادن به تغییر سطح صدای فعلی اجرا کنند، به عنوان مثال، با ارائه یک دستگیره که کاربر بتواند آن را بچرخاند.)

حالت میکروفون

حالات احتمالی میکروفون پس از تکمیل Assist RPC.

Enums
MICROPHONE_MODE_UNSPECIFIED هیچ حالتی مشخص نشده است.
CLOSE_MICROPHONE این سرویس انتظار سوال بعدی از کاربر را ندارد. میکروفون باید خاموش بماند تا زمانی که کاربر آن را دوباره فعال کند.
DIALOG_FOLLOW_ON این سرویس منتظر یک سوال بعدی از کاربر است. هنگامی که پخش AudioOut کامل شد (با شروع یک تماس جدید Assist RPC برای ارسال صدای جدید)، میکروفون باید دوباره باز شود.

ScreenOut

پاسخ خروجی بصری دستیار به پرس و جو. توسط screen_out_config فعال شد.

زمینه های
format

Format

فقط خروجی قالب داده های صفحه نمایش ارائه شده.

data

bytes

فقط خروجی داده‌های خام صفحه‌ای که در نتیجه جستجوی دستیار نمایش داده می‌شوند.

قالب

فرمت های احتمالی داده های صفحه نمایش

Enums
FORMAT_UNSPECIFIED هیچ قالبی مشخص نشده است.
HTML داده ها حاوی یک طرح بندی کامل HTML5 هستند که در UTF-8 کدگذاری شده است، به عنوان مثال <html><body><div>...</div></body></html> . قرار است همراه با پاسخ صوتی ارائه شود. توجه داشته باشید که نوع doctype HTML5 باید در داده های واقعی HTML گنجانده شود.

ScreenOutConfig

فرمت مورد نظر را برای سرور مشخص می کند تا هنگام بازگرداندن پاسخ screen_out از آن استفاده کند.

زمینه های
screen_mode

ScreenMode

حالت صفحه بصری فعلی برای دستگاه در حین صدور پرس و جو.

حالت صفحه نمایش

حالت های ممکن برای خروجی صفحه نمایش بصری در دستگاه.

Enums
SCREEN_MODE_UNSPECIFIED حالت ویدیویی مشخص نشده است. دستیار ممکن است مانند حالت OFF پاسخ دهد.
OFF صفحه خاموش است (یا روشنایی یا تنظیمات دیگر آنقدر پایین تنظیم شده است که قابل مشاهده نیست). دستیار معمولاً در این حالت پاسخی از صفحه نمایش نمی دهد.
PLAYING «دستیار» معمولاً در این حالت یک پاسخ صفحه نمایش جزئی را نشان می دهد.

نتیجه تشخیص گفتار

رونویسی تخمینی عبارتی که کاربر گفته است. این می تواند یک بخش یا حدس کامل درخواست گفتاری کاربر باشد.

زمینه های
transcript

string

متن رونوشت فقط خروجی که بیانگر کلماتی است که کاربر صحبت کرده است.

stability

float

فقط خروجی تخمینی از احتمال عدم تغییر حدس دستیار در مورد این نتیجه. مقادیر از 0.0 (کاملاً ناپایدار) تا 1.0 (کاملاً پایدار و نهایی) متغیر است. پیش فرض 0.0 یک مقدار نگهبان است که نشان می دهد stability تنظیم نشده است.