Package google.assistant.embedded.v1alpha2

Index

EmbeddedAssistant

Dienst, der die Google Assistant API implementiert.

Assist

rpc Assist(AssistRequest) returns (AssistResponse)

Initiiert oder setzt eine Unterhaltung mit dem eingebetteten Assistant-Dienst fort. Bei jedem Aufruf wird ein Umlauf durchgeführt, wobei eine Audioanfrage an den Dienst gesendet und die Audioantwort empfangen wird. Beim Senden von Audiodaten wird bidirektionales Streaming verwendet, um Ergebnisse wie das Ereignis END_OF_UTTERANCE zu empfangen.

Eine Unterhaltung ist eine oder mehrere gRPC-Verbindungen, die jeweils aus mehreren gestreamten Anfragen und Antworten bestehen. Beispiel: Der Nutzer sagt Zu meiner Einkaufsliste hinzufügen und Assistant antwortet mit Was möchtest du hinzufügen?. Die Reihenfolge der gestreamten Anfragen und Antworten in der ersten gRPC-Nachricht könnte so aussehen:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.speech_results.transcript "Zu meiner Einkaufsliste hinzufügen"
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

Der Nutzer sagt dann Bagels und Assistant antwortet mit OK, ich habe Bagels auf deine Einkaufsliste gesetzt. Dies wird als weiterer gRPC-Verbindungsaufruf an die Methode Assist gesendet, wieder mit gestreamten Anfragen und Antworten, z. B.:

  • 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

Obwohl die genaue Reihenfolge der Antworten nicht garantiert werden kann, enthalten sequentielle AssistResponse.audio_out-Nachrichten immer sequenzielle Teile der Audiodaten.

Autorisierungsbereiche

Erfordert den folgenden OAuth-Bereich:

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

Weitere Informationen finden Sie im Autorisierungsleitfaden.

AssistConfig

Gibt an, wie die AssistRequest-Nachrichten verarbeitet werden sollen.

Felder
audio_out_config

AudioOutConfig

Erforderlich: Gibt an, wie die zurückgegebenen Audiodaten formatiert werden sollen.

screen_out_config

ScreenOutConfig

Optional. Gibt das Format an, das verwendet werden soll, wenn der Server eine visuelle Bildschirmantwort zurückgibt.

dialog_state_in

DialogStateIn

Erforderlich. Gibt den aktuellen Status des Dialogfelds an.

device_config

DeviceConfig

Gerätekonfiguration, die ein bestimmtes Gerät eindeutig identifiziert.

debug_config

DebugConfig

Optional. Debugging-Parameter für den gesamten Assist-RPC.

Union-Feld type.

Für type ist nur einer der folgenden Werte zulässig:
audio_in_config

AudioInConfig

Gibt an, wie die nachfolgend eingehenden Audiodaten verarbeitet werden. Erforderlich, wenn in nachfolgenden Anfragen AssistRequest.audio_in Byte angegeben werden.

text_query

string

Die Texteingabe, die an Assistant gesendet werden soll. Dieses Feld kann über eine Textschnittstelle ausgefüllt werden, wenn keine Audioeingabe verfügbar ist.

AssistRequest

Die vom Client gesendete Nachricht der obersten Ebene. Clients müssen mindestens zwei, in der Regel zahlreiche AssistRequest-Nachrichten senden. Die erste Nachricht muss eine config-Nachricht und keine audio_in-Daten enthalten. Alle nachfolgenden Nachrichten müssen audio_in-Daten enthalten und dürfen keine config-Nachrichten enthalten.

Felder
Union-Feld type. In jeder AssistRequest muss genau eines dieser Felder angegeben werden. Für type ist nur einer der folgenden Werte zulässig:
config

AssistConfig

Die config-Nachricht stellt dem Erkennungsmodul Informationen zur Verarbeitung der Anfrage zur Verfügung. Die erste AssistRequest-Nachricht muss eine config-Nachricht enthalten.

audio_in

bytes

Die zu erkennenden Audiodaten. Sequenzielle Blöcke von Audiodaten werden in sequenziellen AssistRequest-Nachrichten gesendet. Die erste AssistRequest-Nachricht darf keine audio_in-Daten enthalten, alle nachfolgenden AssistRequest-Nachrichten müssen audio_in-Daten enthalten. Die Audiobyte müssen wie in AudioInConfig angegeben codiert sein. Audiodaten müssen annähernd in Echtzeit gesendet werden (16.000 Samples pro Sekunde). Wenn Audiodaten deutlich schneller oder langsamer gesendet werden, wird ein Fehler zurückgegeben.

AssistResponse

Die vom Client empfangene Nachricht der obersten Ebene. Eine Reihe von einer oder mehreren AssistResponse-Nachrichten wird zurück an den Client gestreamt.

Felder
event_type

EventType

Nur Ausgabe Gibt den Ereignistyp an.

audio_out

AudioOut

Nur Ausgabe Die Audiodaten mit der Antwort von Assistant auf die Anfrage.

screen_out

ScreenOut

Nur Ausgabe Enthält die visuelle Antwort des Assistenten auf die Abfrage.

device_action

DeviceAction

Nur Ausgabe enthält die Aktion, die von der Abfrage mit den entsprechenden Nutzlasten und semantischem Parsing ausgelöst wird.

speech_results[]

SpeechRecognitionResult

Nur Ausgabe. Diese wiederholte Liste enthält keine oder mehr Spracherkennungsergebnisse, die aufeinanderfolgenden Teilen der aktuell verarbeiteten Audiodaten entsprechen, beginnend mit dem Teil, der dem frühesten Audio (und dem stabilsten Teil) entspricht, bis zum Teil, der dem neuesten Audio entspricht. Die Strings können verkettet werden, um die vollständige Antwort in Bearbeitung anzuzeigen. Nach Abschluss der Spracherkennung enthält diese Liste ein Element mit stability von 1.0.

dialog_state_out

DialogStateOut

Nur Ausgabe Enthält Ausgaben, die sich auf die Abfrage des Nutzers beziehen.

debug_info

DebugInfo

Nur Ausgabe Debugging-Informationen für Entwickler. Wird nur zurückgegeben, wenn return_debug_info bei der Anfrage auf „true“ gesetzt wurde.

EventType

Gibt den Ereignistyp an.

Enums
EVENT_TYPE_UNSPECIFIED Kein Ereignis angegeben.
END_OF_UTTERANCE Mit diesem Ereignis wird angezeigt, dass vom Server das Ende der sprachlichen Äußerung des Nutzers erkannt wurde und keine weiteren Sprachdaten erwartet werden. Daher werden keine weiteren Audiodaten vom Server verarbeitet (möglicherweise gibt er jedoch noch weitere Ergebnisse aus). Der Client sollte keine weiteren Audiodaten mehr senden, die gRPC-Verbindung in eine Richtung schließen und auf weitere Ergebnisse warten, bis die gRPC-Verbindung vom Server geschlossen wurde.

AudioInConfig

Gibt an, wie die audio_in-Daten verarbeitet werden, die in nachfolgenden Anfragen bereitgestellt werden. Empfohlene Einstellungen finden Sie in den Best Practices für das Google Assistant SDK.

Felder
encoding

Encoding

Erforderlich Codierung der Audiodaten, die in allen audio_in-Nachrichten gesendet werden.

sample_rate_hertz

int32

Erforderlich: Abtastrate (in Hertz) der Audiodaten, die in allen audio_in-Nachrichten gesendet werden. Zulässige Werte liegen zwischen 16.000 und 24.000, 16.000 ist optimal. Stellen Sie die Abtastrate der Audioquelle auf 16.000 Hz ein, um die besten Ergebnisse zu erzielen. Falls dies nicht möglich ist, verwenden Sie die native Abtastrate der Audioquelle (anstatt eine erneute Abtastung durchzuführen).

Codierung

Die Audiocodierung der in der Audionachricht gesendeten Daten. Audio muss einkanalig (Mono) sein.

Enums
ENCODING_UNSPECIFIED Nicht angegeben. Gibt das Ergebnis google.rpc.Code.INVALID_ARGUMENT zurück.
LINEAR16 Unkomprimierte 16-Bit-Little-Endian-Samples mit Vorzeichen (Lineare PCM). Diese Codierung umfasst keinen Header, sondern nur die Rohbyte des Audios.
FLAC Als Codierung wird FLAC (Free Lossless Audio Codec) empfohlen, da sie verlustfrei ist, sodass die Erkennung nicht beeinträchtigt wird, und nur etwa halb so viel Bandbreite wie LINEAR16 benötigt. Diese Codierung umfasst den Stream-Header FLAC, gefolgt von Audiodaten. 16-Bit- und 24-Bit-Beispiele werden unterstützt, es werden jedoch nicht alle Felder in STREAMINFO unterstützt.

AudioOut

Die Audiodatei mit der Antwort von Assistant auf die Anfrage. Sequenzielle Blöcke von Audiodaten werden in aufeinanderfolgenden AssistResponse-Nachrichten empfangen.

Felder
audio_data

bytes

Nur Ausgabe: Die Audiodaten, die die Antwort von Assistant auf die Anfrage enthalten. Sequenzielle Blöcke von Audiodaten werden in aufeinanderfolgenden AssistResponse-Nachrichten empfangen.

AudioOutConfig

Gibt das gewünschte Format für den Server an, wenn er audio_out-Nachrichten zurückgibt.

Felder
encoding

Encoding

Erforderlich. Die Codierung von Audiodaten, die in allen audio_out-Nachrichten zurückgegeben werden sollen.

sample_rate_hertz

int32

Erforderlich. Die Abtastrate der Audiodaten, die in audio_out-Nachrichten zurückgegeben werden, in Hertz. Gültige Werte: 16.000–24.000.

volume_percentage

int32

Erforderlich. Aktuelle Lautstärkeeinstellung für die Audioausgabe des Geräts. Gültige Werte sind 1 bis 100 (entspricht 1% bis 100%).

Codierung

Audiocodierung der Daten, die in der Audionachricht zurückgegeben werden. Sofern nicht unten angegeben, handelt es sich bei allen Codierungen um Rohaudiobyte ohne Header.

Enums
ENCODING_UNSPECIFIED Nicht angegeben. Gibt das Ergebnis google.rpc.Code.INVALID_ARGUMENT zurück.
LINEAR16 Unkomprimierte 16-Bit-Little-Endian-Samples mit Vorzeichen (Lineare PCM).
MP3 MP3-Audiocodierung. Die Abtastrate wird in der Nutzlast codiert.
OPUS_IN_OGG Opus-codierte Audiodaten, eingebettet in einem OGG-Container. Das Ergebnis ist eine Datei, die nativ auf Android-Geräten und in einigen Browsern (z. B. Chrome) abgespielt werden kann. Die Qualität der Codierung ist bei gleicher Bitrate deutlich höher als bei MP3. Die Abtastrate wird in der Nutzlast codiert.

DebugConfig

Debugging-Parameter für die aktuelle Anfrage.

Felder
return_debug_info

bool

Wenn dieses Feld auf „true“ gesetzt ist, kann das Feld debug_info in AssistResponse ausgefüllt werden. Allerdings erhöht sich dadurch die Latenz der Antworten erheblich.

DebugInfo

Informationen zur Fehlerbehebung für Entwickler. Wird nur zurückgegeben, wenn return_debug_info bei der Anfrage auf „true“ gesetzt wurde.

Felder
aog_agent_to_assistant_json

string

Die ursprüngliche JSON-Antwort von einem Action-on-Google-Agent an den Google-Server. Siehe AppResponse. Es wird nur ausgefüllt, wenn der Ersteller des AoG-Projekts Inhaber des AoG-Projekts ist und sich das AoG-Projekt im Vorschaumodus befindet.

DeviceAction

Die an das Gerät zurückgegebene Antwort, wenn der Nutzer eine Geräteaktion ausgelöst hat. Beispielsweise würde ein Gerät, das die Abfrage Schalte das Licht einschalten unterstützt, einen DeviceAction-Wert mit einer JSON-Nutzlast empfangen, die die Semantik der Anfrage enthält.

Felder
device_request_json

string

JSON mit der Gerätebefehlsantwort, die von der ausgelösten Geräteaktionsgrammatik generiert wurde. Das Format wird vom Intent action.devices.EXECUTE für eine bestimmte Trait vorgegeben.

DeviceConfig

Pflichtfelder: Felder, über die Assistant das Gerät identifizieren kann.

Weitere Informationen

Felder
device_id

string

Erforderlich: Eindeutige Kennung des Geräts. Die ID darf maximal 128 Zeichen lang sein. Beispiel: DBCDW098234. Sie MUSS mit der Geräte-ID übereinstimmen, die von der Geräteregistrierung zurückgegeben wurde. Diese device_id wird für den Abgleich mit den registrierten Geräten des Nutzers verwendet, um die unterstützten Eigenschaften und Funktionen dieses Geräts abzurufen. Diese Informationen sollten sich bei Geräteneustarts nicht ändern. Er sollte jedoch nicht bei einem Zurücksetzen auf die Werkseinstellungen gespeichert werden.

device_model_id

string

Erforderlich: Eindeutige Kennung des Gerätemodells. Die Kombination aus device_model_id und device_id muss zuvor über die Geräteregistrierung verknüpft worden sein.

DeviceLocation

Es gibt drei Quellen für Standorte. Sie werden mit dieser Priorität verwendet:

  1. Dies DeviceLocation, das hauptsächlich für Mobilgeräte mit GPS verwendet wird .
  2. Der vom Nutzer bei der Geräteeinrichtung angegebene Standort; pro Nutzer und Gerät. Dieser Speicherort wird verwendet, wenn DeviceLocation nicht angegeben ist.
  3. Anhand der IP-Adresse abgeleiteter Standort Dieser Parameter wird nur verwendet, wenn keine der oben genannten Optionen festgelegt ist.
Felder
coordinates

LatLng

Breiten- und Längengrad des Geräts.

DialogStateIn

Liefert Informationen zum aktuellen Dialogstatus.

Felder
conversation_state

bytes

Erforderlich. Dieses Feld muss immer auf den Wert DialogStateOut.conversation_state festgelegt werden, der beim vorherigen Assist-RPC zurückgegeben wurde. Es sollte nur weggelassen werden (Feld nicht festgelegt), wenn es zuvor keinen Assist-RPC gab, da dies der erste Assist-RPC ist, der von diesem Gerät nach der Ersteinrichtung und/oder dem Zurücksetzen auf die Werkseinstellungen durchgeführt wurde.

language_code

string

Erforderlich Sprache der Anfrage in der IETF BCP 47-Syntax (z. B. „en-US“). Weitere Informationen finden Sie unter Sprachunterstützung. Wenn du in der Google Assistant App auf deinem Smartphone im Menü Einstellungen eine Sprache für dieses device_id ausgewählt hast, wird dieser Wert überschrieben.

device_location

DeviceLocation

Optional. Der Standort des Geräts, von dem die Abfrage stammt.

is_new_conversation

bool

Optional. Wenn der Wert "true" ist, behandelt der Server die Anfrage als neue Unterhaltung und verwendet nicht den Status aus der vorherigen Anfrage. Setzen Sie dieses Feld auf „true“, wenn die Unterhaltung neu gestartet werden soll, z. B. nach einem Geräteneustart oder nach einem längeren Zeitraum seit der letzten Anfrage.

DialogStateOut

Der Status des Dialogfelds, der sich aus der Suchanfrage des Nutzers ergibt. Es können mehrere dieser Nachrichten empfangen werden.

Felder
supplemental_display_text

string

Nur Ausgabe: Zusätzlicher Anzeigetext von Assistant. Dies kann mit der in AssistResponse.audio_out gesprochenen Sprache übereinstimmen oder es können zusätzliche Informationen sein, die das Verständnis des Nutzers erleichtern.

conversation_state

bytes

Nur Ausgabe: Statusinformationen für den nachfolgenden Assist-RPC. Dieser Wert sollte im Client gespeichert und im Feld DialogStateIn.conversation_state mit dem nächsten Assist-RPC zurückgegeben werden. Der Client muss diesen Wert nicht interpretieren oder anderweitig verwenden. Diese Informationen sollten bei Geräteneustarts gespeichert bleiben. Dieser Wert sollte jedoch beim Zurücksetzen auf die Werkseinstellungen gelöscht (nicht im Client gespeichert) werden.

microphone_mode

MicrophoneMode

Nur Ausgabe: Gibt den Mikrofonmodus an, nachdem dieser Assist-RPC verarbeitet wurde.

volume_percentage

int32

Nur Ausgabe Der Lautstärkepegel wurde aktualisiert. Der Wert ist 0 oder wird weggelassen (also keine Änderung), es sei denn, ein Sprachbefehl wie Lautstärke erhöhen oder Lautstärkestufe 4 einstellen wurde erkannt. In diesem Fall liegt der Wert zwischen 1 und 100 (entspricht der neuen Lautstärke von 1% bis 100%). In der Regel sollte ein Client diesen Lautstärkepegel beim Abspielen der audio_out-Daten verwenden und diesen als aktuellen Lautstärkepegel beibehalten und im AudioOutConfig der nächsten AssistRequest angeben. Einige Kunden implementieren möglicherweise auch andere Möglichkeiten, die aktuelle Lautstärke zu ändern, z. B. durch Bereitstellung eines Drehknopfs, den der Nutzer drehen kann.

MicrophoneMode

Mögliche Status des Mikrofons nach Abschluss eines Assist-RPC.

Enums
MICROPHONE_MODE_UNSPECIFIED Kein Modus angegeben.
CLOSE_MICROPHONE Der Dienst erwartet keine Folgefrage vom Nutzer. Das Mikrofon sollte ausgeschaltet bleiben, bis der Nutzer es wieder aktiviert.
DIALOG_FOLLOW_ON Der Dienst erwartet eine Folgefrage vom Nutzer. Das Mikrofon sollte wieder eingeschaltet werden, wenn die Wiedergabe von AudioOut abgeschlossen ist. Dazu wird ein neuer Assist-RPC-Aufruf zum Senden der neuen Audiodaten gestartet.

ScreenOut

Die visuelle Ausgabe von Assistant als Antwort auf eine Anfrage. Aktiviert durch screen_out_config.

Felder
format

Format

Nur Ausgabe. Das Format der bereitgestellten Bildschirmdaten.

data

bytes

Nur Ausgabe. Die Rohdaten auf dem Bildschirm, die als Ergebnis der Assistant-Anfrage angezeigt werden.

Format

Mögliche Formate der Bildschirmdaten.

Enums
FORMAT_UNSPECIFIED Kein Format angegeben.
HTML Die Daten enthalten ein vollständiges HTML5-Layout, das in UTF-8 codiert ist, z.B. <html><body><div>...</div></body></html>. Er soll zusammen mit der Audioantwort gerendert werden. Der HTML5-DOCTYPE muss in den tatsächlichen HTML-Daten enthalten sein.

ScreenOutConfig

Gibt das gewünschte Format für den Server an, wenn er eine screen_out-Antwort zurückgibt.

Felder
screen_mode

ScreenMode

Aktueller visueller Bildschirmmodus für das Gerät beim Senden der Abfrage.

ScreenMode

Mögliche Modi für die visuelle Bildschirmausgabe auf dem Gerät.

Enums
SCREEN_MODE_UNSPECIFIED Kein Videomodus angegeben. Assistant antwortet eventuell wie im OFF-Modus.
OFF Das Display ist ausgeschaltet (oder die Helligkeit ist so niedrig, dass es nicht sichtbar ist). Assistant gibt in diesem Modus normalerweise keine Bildschirmantwort zurück.
PLAYING In diesem Modus gibt Assistant in der Regel eine Teilantwort auf dem Bildschirm zurück.

SpeechRecognitionResult

Die geschätzte Transkription einer Wortgruppe, die der Nutzer gesprochen hat. Dies kann ein einzelnes Segment oder die vollständige Vermutung der gesprochenen Suchanfrage des Nutzers sein.

Felder
transcript

string

Nur Ausgabe. Transkriptionstext mit den vom Nutzer gesprochenen Wörtern.

stability

float

Nur Ausgabe. Eine Schätzung der Wahrscheinlichkeit, dass Assistant seine Vermutung zu diesem Ergebnis nicht ändert. Die Werte reichen von 0,0 (vollständig instabil) bis 1,0 (vollständig stabil und endgültig). Der Standardwert von 0,0 ist ein Sentinel-Wert, der angibt, dass stability nicht festgelegt wurde.