Package google.assistant.embedded.v1alpha2

Indeks

EmbeddedAssistant

Usługa, która korzysta z interfejsu Google Assistant API.

Asysta

rpc Assist(AssistRequest) returns (AssistResponse)

Rozpoczyna lub kontynuuje rozmowę z umieszczoną usługą Asystenta. Każde połączenie jest wysyłane w obie strony, wysyłane do usługi żądanie dźwiękowe i odbierane w odpowiedzi audio. Używa dwukierunkowego przesyłania strumieniowego do odbierania wyników, np. zdarzenia END_OF_UTTERANCE, podczas wysyłania dźwięku.

Rozmowa to co najmniej jedno połączenie gRPC, z których każde składa się z kilku przesyłanych strumieniowo żądań i odpowiedzi. Na przykład użytkownik powie Dodaj do mojej listy zakupów, a Asystent odpowie Co chcesz dodać?. Sekwencja przesyłanych strumieniowo żądań i odpowiedzi w pierwszym komunikacie gRPC mogłaby wyglądać tak:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.speech_results.transcript „dodaj do mojej listy zakupów”
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

Następnie użytkownik mówi bajgle, a Asystent odpowiada OK, dodałem bajgle do listy zakupów. Jest ono wysyłane jako kolejne wywołanie połączenia gRPC do metody Assist, ponownie ze strumieniowymi żądaniami i odpowiedziami, takimi jak:

  • 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

Chociaż dokładna kolejność odpowiedzi nie jest gwarantowana, kolejne komunikaty AssistResponse.audio_out zawsze zawierają sekwencyjne fragmenty dźwięku.

Zakresy autoryzacji

Wymaga następującego zakresu OAuth:

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

Więcej informacji znajdziesz w przewodniku uwierzytelniania.

AssistConfig

Określa sposób przetwarzania wiadomości AssistRequest.

Pola
audio_out_config

AudioOutConfig

Wymagane – określa sposób formatowania dźwięku, który ma być zwracany.

screen_out_config

ScreenOutConfig

Opcjonalny określa format, który ma być używany, gdy serwer zwraca odpowiedź na ekran.

dialog_state_in

DialogStateIn

Wymagane Reprezentuje bieżący stan okna.

device_config

DeviceConfig

Konfiguracja, która jednoznacznie identyfikuje konkretne urządzenie.

debug_config

DebugConfig

Opcjonalne parametry debugowania dla całego wywołania RPC Assist.

Pole sumy type.

type może mieć tylko jedną z tych wartości:
audio_in_config

AudioInConfig

Określa sposób przetwarzania następnego przychodzącego dźwięku. Wymagane, jeśli w kolejnych żądaniach będzie podawane AssistRequest.audio_in B.

text_query

string

Tekst, który ma zostać wysłany do Asystenta. Jeśli dane wejściowe audio są niedostępne, można je uzupełnić z interfejsu tekstowego.

AssistRequest

Wiadomość najwyższego poziomu wysłana przez klienta. Klienci muszą wysłać co najmniej dwie (zwykle dużą liczbę wiadomości) wiadomości AssistRequest. Pierwsza wiadomość musi zawierać wiadomość config i nie może zawierać danych audio_in. Wszystkie kolejne wiadomości muszą zawierać dane audio_in i nie mogą zawierać wiadomości config.

Pola
Pole sumy type. W każdym polu AssistRequest musisz podać dokładnie jedno z tych pól. type może mieć tylko jedną z tych wartości:
config

AssistConfig

Komunikat config przekazuje modułowi rozpoznawania informacje określające sposób przetworzenia żądania. Pierwsza wiadomość AssistRequest musi zawierać wiadomość config.

audio_in

bytes

Dane dźwiękowe do rozpoznania. Kolejne fragmenty danych dźwiękowych są wysyłane w formie kolejnych komunikatów w trybie AssistRequest. Pierwsza wiadomość AssistRequest nie może zawierać danych audio_in, a wszystkie kolejne wiadomości AssistRequest muszą zawierać dane audio_in. Bajty audio muszą być zakodowane w sposób określony w zasadzie AudioInConfig. Dźwięk musi być wysyłany w czasie zbliżonym do rzeczywistego (16 000 próbek na sekundę). Jeśli dźwięk jest przesyłany znacznie szybciej lub wolniej, zwracany jest błąd.

AssistResponse

Wiadomość najwyższego poziomu odebrana przez klienta. Seria co najmniej jednej wiadomości w usłudze AssistResponse jest przesyłana z powrotem do klienta.

Pola
event_type

EventType

Tylko dane wyjściowe Wskazuje typ zdarzenia.

audio_out

AudioOut

Tylko dane wyjściowe – dźwięk zawierający odpowiedź Asystenta na zapytanie.

screen_out

ScreenOut

Tylko dane wyjściowe Zawiera wizualną odpowiedź Asystenta na zapytanie.

device_action

DeviceAction

Tylko dane wyjściowe Zawiera działanie aktywowane przez zapytanie z odpowiednimi ładunkami i analizą semantyczną.

speech_results[]

SpeechRecognitionResult

Tylko dane wyjściowe: ta lista powtarzana zawiera zero lub więcej wyników rozpoznawania mowy, które odpowiadają kolejnym przetwarzanym obecnie częściom dźwięku – poczynając od fragmentu odpowiadającego najwcześniejszemu utwórowi (i najbardziej stabilnej) po fragment odpowiadający najnowszemu dźwiękowi. Możesz połączyć ciągi tekstowe, aby wyświetlić pełną odpowiedź w toku. Po zakończeniu rozpoznawania mowy lista będzie zawierać jeden element z stability z 1.0.

dialog_state_out

DialogStateOut

Tylko dane wyjściowe Zawiera dane wyjściowe związane z zapytaniem użytkownika.

debug_info

DebugInfo

Tylko dane wyjściowe – dane debugowania dla dewelopera. Zwracana tylko wtedy, gdy w żądaniu return_debug_info ustawiono wartość Prawda.

EventType

Wskazuje typ zdarzenia.

Wartości w polu enum
EVENT_TYPE_UNSPECIFIED Nie określono zdarzenia.
END_OF_UTTERANCE To zdarzenie oznacza, że serwer wykrył koniec wypowiedzi użytkownika i nie oczekuje żadnej dodatkowej mowy. Dlatego serwer nie przetwarza dodatkowego dźwięku (chociaż może później zwracać dodatkowe wyniki). Klient powinien przestać wysyłać dodatkowe dane audio, zamknąć do połowy połączenie gRPC i poczekać na dodatkowe wyniki, aż serwer zamknie połączenie gRPC.

AudioInConfig

Określa, jak przetwarzać dane audio_in przekazywane w kolejnych żądaniach. Zalecane ustawienia znajdziesz w sprawdzonych metodach dotyczących pakietu SDK Asystenta Google.

Pola
encoding

Encoding

Wymagane kodowanie danych dźwiękowych wysyłanych we wszystkich wiadomościach typu audio_in.

sample_rate_hertz

int32

Wymagane – częstotliwość próbkowania (w hercach) danych dźwiękowych wysłanych we wszystkich wiadomościach typu audio_in. Prawidłowe wartości mieszczą się w przedziale od 16 000 do 24 000, ale optymalna to 16 000. Aby uzyskać najlepsze wyniki, ustaw częstotliwość próbkowania dla źródła dźwięku na 16 000 Hz. Jeśli jest to niemożliwe, użyj natywnej częstotliwości próbkowania ze źródła audio (zamiast ponownego próbkowania).

Kodowanie

Kodowanie dźwięku danych wysłanych w wiadomości głosowej. Dźwięk musi być jednokanałowy (mono).

Wartości w polu enum
ENCODING_UNSPECIFIED Nie określono. Zwrócony wynik to google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Nieskompresowane, podpisane 16-bitowe próbki little-endian (Linear PCM). Kodowanie nie obejmuje nagłówka, a jedynie nieprzetworzone bajty audio.
FLAC Zalecane jest kodowanie FLAC (Free Lossless Audio Codec), ponieważ jest ono bezstratne, dzięki czemu rozpoznawanie nie jest zagrożone i wymaga tylko około połowy przepustowości LINEAR16. To kodowanie obejmuje nagłówek strumienia FLAC, po którym następuje dane audio. Obsługuje on 16- i 24-bitowe próbki, ale nie wszystkie pola w STREAMINFO są obsługiwane.

AudioOut

Nagranie z odpowiedzią Asystenta na pytanie. Kolejne fragmenty danych dźwiękowych są odbierane w sekwencji komunikatów AssistResponse.

Pola
audio_data

bytes

Tylko dane wyjściowe: dane dźwiękowe zawierające odpowiedź Asystenta na zapytanie. Kolejne fragmenty danych dźwiękowych są odbierane w sekwencji komunikatów AssistResponse.

AudioOutConfig

Określa format, który ma być używany przez serwer przy zwracaniu wiadomości audio_out.

Pola
encoding

Encoding

Wymagane kodowanie danych dźwiękowych, które mają być zwracane we wszystkich wiadomościach typu audio_out.

sample_rate_hertz

int32

Wymagane: częstotliwość próbkowania danych audio zwracanych w wiadomościach (audio_out) w hercach danych dźwiękowych. Prawidłowe wartości to: 16 000–24 000.

volume_percentage

int32

Wymagane: bieżące ustawienie głośności wyjścia audio urządzenia. Prawidłowe wartości to od 1 do 100 (odpowiadające 1%–100%).

Kodowanie

Kodowanie dźwięku danych zwróconych w wiadomości głosowej. Wszystkie kodowanie są nieprzetworzonymi bajtami audio bez nagłówka, z wyjątkiem sytuacji opisanych poniżej.

Wartości w polu enum
ENCODING_UNSPECIFIED Nie określono. Zwrócony wynik to google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Nieskompresowane, podpisane 16-bitowe próbki little-endian (Linear PCM).
MP3 Kodowanie audio MP3. Częstotliwość próbkowania jest kodowana w ładunku.
OPUS_IN_OGG Dźwięk w kodowaniu opus zapakowany w kontenerze Ogg. Powstanie plik, który można natywnie odtwarzać na Androidzie i w niektórych przeglądarkach (np. Chrome). Jakość kodowania jest znacznie wyższa niż jakość MP3 przy tej samej szybkości transmisji bitów. Częstotliwość próbkowania jest kodowana w ładunku.

DebugConfig

Parametry debugowania bieżącego żądania.

Pola
return_debug_info

bool

Gdy to pole ma wartość Prawda, pole debug_info w AssistResponse może być wypełnione. Znacznie wydłuży to jednak czas oczekiwania na odpowiedź.

DebugInfo

Dane debugowania dla dewelopera. Zwracana tylko wtedy, gdy w żądaniu return_debug_info ustawiono wartość Prawda.

Pola
aog_agent_to_assistant_json

string

Oryginalna odpowiedź JSON od agenta Action-on-Google do serwera Google. Zobacz AppResponse. Pole jest wypełniane tylko wtedy, gdy twórca żądań jest właścicielem projektu AoG, a projekt AoG jest w trybie podglądu.

DeviceAction

Odpowiedź zwracana na urządzenie, jeśli użytkownik wywołał akcję urządzenia. Na przykład urządzenie, które obsługuje zapytanie Turn on the light, otrzyma na przykład żądanie DeviceAction z ładunkiem JSON zawierającym semantykę żądania.

Pola
device_request_json

string

Plik JSON zawierający odpowiedź na polecenie urządzenia wygenerowaną na podstawie gramatyki akcji na urządzeniu. Format jest określony przez intencję action.devices.EXECUTE dla danej cechy.

DeviceConfig

Wymagane pola identyfikujące urządzenie przez Asystenta.

Zobacz także:

Pola
device_id

string

Wymagany unikalny identyfikator urządzenia. Identyfikator może mieć maksymalnie 128 znaków. Przykład: DBCDW098234. Ten identyfikator MUSI być zgodny z identyfikatorem urządzenia zwróconym podczas rejestracji urządzenia. Ten identyfikator device_id służy do porównywania zarejestrowanych urządzeń użytkownika w celu wyszukiwania obsługiwanych cech i możliwości tego urządzenia. Te informacje nie powinny zmieniać się po ponownym uruchomieniu urządzenia. Nie należy go jednak zapisywać po przywróceniu ustawień fabrycznych.

device_model_id

string

Wymagany unikalny identyfikator modelu urządzenia. Kombinacja atrybutów device_model_id i device_id musi zostać wcześniej powiązana przez rejestrację urządzenia.

DeviceLocation

Istnieją trzy źródła lokalizacji. Są one używane w taki sposób:

  1. To urządzenie DeviceLocation, które jest używane głównie na urządzeniach mobilnych z GPS-em .
  2. Lokalizację podaną przez użytkownika podczas konfiguracji urządzenia określa użytkownik. Ta lokalizacja będzie używana, jeśli nie podasz DeviceLocation.
  3. Lokalizacja wywnioskowana na podstawie adresu IP. Jest ona używana tylko wtedy, gdy nie określono żadnego z powyższych.
Pola
coordinates

LatLng

Długość i szerokość geograficzna urządzenia.

DialogStateIn

Zawiera informacje o bieżącym stanie okna dialogowego.

Pola
conversation_state

bytes

Wymagane – to pole musi zawsze zawierać wartość DialogStateOut.conversation_state, która została zwrócona w poprzednim RPC Assist. Należy je pominąć (nieustawione pole) tylko wtedy, gdy nie było wcześniejszego wywołania RPC Assist, ponieważ jest to pierwsze wywołanie RPC Assist wykonane przez to urządzenie po pierwszej konfiguracji lub przywróceniu ustawień fabrycznych.

language_code

string

Wymagany język żądania w składni IETF BCP 47 (np. „en-US”). Więcej informacji znajdziesz w artykule Obsługa języków. Jeśli język dla tego urządzenia (device_id) został wybrany w menu Ustawienia w aplikacji Asystent Google na telefonie, ten wybór zastąpi tę wartość.

device_location

DeviceLocation

Opcjonalne: lokalizacja urządzenia, z którego pochodzi zapytanie.

is_new_conversation

bool

Opcjonalny – jeśli ma wartość true (prawda), serwer potraktuje żądanie jako nową rozmowę i nie użyje stanu z poprzedniego żądania. Ustaw to pole na „true” (prawda), gdy rozmowa ma zostać ponownie uruchomiona, na przykład po ponownym uruchomieniu urządzenia lub gdy upłynęło dużo czasu od poprzedniego zapytania.

DialogStateOut

Stan okna spowodowanego zapytaniem użytkownika. Wiele z tych wiadomości może być odbieranych.

Pola
supplemental_display_text

string

Tylko dane wyjściowe – dodatkowy tekst wyświetlany przez Asystenta. Może to być ta sama wypowiedź w języku: AssistResponse.audio_out lub dodatkowe informacje, które pomogą użytkownikowi zrozumieć treść.

conversation_state

bytes

Tylko dane wyjściowe – informacje o stanie dla kolejnego RPC Assist. Ta wartość powinna zostać zapisana w kliencie i zwrócona w polu DialogStateIn.conversation_state przy następnym wywołaniu RPC Assist. (Klient nie musi interpretować ani w inny sposób używać tej wartości). Te informacje powinny być zapisywane podczas ponownego uruchamiania urządzenia. Ta wartość powinna jednak zostać wyczyszczona (nie zapisana u klienta) podczas przywracania ustawień fabrycznych.

microphone_mode

MicrophoneMode

Tylko dane wyjściowe – określa tryb mikrofonu po przetworzeniu tego wywołania RPC Assist.

volume_percentage

int32

Tylko na wyjściu Zaktualizowano poziom głośności. Wartość będzie wynosić 0 lub jest pomijana (oznacza brak zmian), chyba że rozpoznano polecenie głosowe, np. Zwiększ głośność lub Ustaw głośność 4. W takim przypadku wartość mieści się w zakresie od 1 do 100 (odpowiada nowemu poziomowi głośności od 1% do 100%). Zazwyczaj klient powinien używać tego poziomu głośności podczas odtwarzania danych audio_out. Zachowaj tę wartość na bieżącym poziomie głośności i dostarczaj ją w AudioOutConfig nast. AssistRequest. (Niektórzy klienci mogą też wdrażać inne sposoby umożliwiające zmianę bieżącego poziomu głośności, na przykład dostarczając pokrętło, które użytkownik może obrócić).

MicrophoneMode

Możliwe stany mikrofonu po zakończeniu RPC Assist.

Wartości w polu enum
MICROPHONE_MODE_UNSPECIFIED Nie określono trybu.
CLOSE_MICROPHONE Usługa nie oczekuje od użytkownika kolejnego pytania. Mikrofon powinien pozostać wyłączony, dopóki użytkownik go ponownie nie aktywuje.
DIALOG_FOLLOW_ON Usługa oczekuje od użytkownika kolejnego pytania. Mikrofon powinien zostać ponownie włączony po zakończeniu odtwarzania elementu AudioOut (przez rozpoczęcie nowego wywołania RPC Assist w celu wysłania nowego dźwięku).

ScreenOut

Wizualna odpowiedź Asystenta na zapytanie. Włączona przez usługę screen_out_config.

Pola
format

Format

Tylko dane wyjściowe – format wyświetlanych danych ekranu.

data

bytes

Tylko dane wyjściowe: nieprzetworzone dane ekranu wyświetlane w wyniku zapytania do Asystenta.

Format

Możliwe formaty danych ekranu.

Wartości w polu enum
FORMAT_UNSPECIFIED Nie określono formatu.
HTML Dane będą zawierać w pełni sformatowany układ HTML5 zakodowany w UTF-8, np. <html><body><div>...</div></body></html>. Powinien być renderowany razem z odpowiedzią głosową. Pamiętaj, że w danych HTML należy uwzględnić format doctype HTML5.

ScreenOutConfig

Określa format, który ma być używany przez serwer przy zwracaniu odpowiedzi screen_out.

Pola
screen_mode

ScreenMode

Bieżący tryb wizualnego ekranu urządzenia podczas wysyłania zapytania.

ScreenMode

Możliwe tryby wizualnego wyświetlania ekranu na urządzeniu.

Wartości w polu enum
SCREEN_MODE_UNSPECIFIED Nie określono trybu wideo. Asystent może reagować tak, jakby był w trybie OFF.
OFF Ekran jest wyłączony (lub ma ustawioną tak niską jasność bądź inne ustawienia, że jest niewidoczna). W tym trybie Asystent zazwyczaj nie zwraca odpowiedzi ekranu.
PLAYING W tym trybie Asystent zwykle zwraca odpowiedź częściowo na ekranie.

SpeechRecognitionResult

Szacowana transkrypcja wyrażenia wypowiedzianego przez użytkownika. Może to być pojedynczy segment lub pełne odgadnięcie wypowiedzi użytkownika.

Pola
transcript

string

Tylko dane wyjściowe: tekst transkrypcji reprezentujący słowa wypowiedziane przez użytkownika.

stability

float

Tylko dane wyjściowe – oszacowanie prawdopodobieństwa, że Asystent nie zmieni swojej przypuszczalnej kwestii dotyczącej tego wyniku. Wartości pochodzą z zakresu od 0,0 (całkowicie niestabilny) do 1,0 (całkowicie stabilne i ostateczne). Wartość domyślna (0,0) to wartość wskaźnika, która oznacza, że stability nie została ustawiona.