Package google.assistant.embedded.v1alpha1

Index

EmbeddedAssistant

Dienst, der die Google Assistant API implementiert.

Converse

rpc Converse(ConverseRequest) returns (ConverseResponse)

Initiiert oder setzt eine Unterhaltung mit dem eingebetteten Assistentendienst 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 der Assistent antwortet mit Was möchtest du hinzufügen?. Die Reihenfolge der gestreamten Anfragen und Antworten in der ersten gRPC-Nachricht könnte so aussehen:

  • 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

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

  • 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

Obwohl die genaue Reihenfolge der Antworten nicht garantiert ist, enthalten sequenzielle ConverseResponse.audio_out-Nachrichten immer sequenzielle Teile der Audiodaten.

Autorisierung

Erfordert den folgenden OAuth-Bereich:

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

Weitere Informationen finden Sie im Autorisierungsleitfaden.

AudioInConfig

Gibt an, wie die audio_in-Daten verarbeitet werden, die in nachfolgenden Anfragen bereitgestellt werden. Empfohlene Einstellungen finden Sie in den Best Practices zur Google Assistant gRPC API.

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. Die einzige unterstützte Sprache ist „en-US“.

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 des Assistenten auf die Anfrage. Sequenzielle Blöcke von Audiodaten werden in aufeinanderfolgenden ConverseResponse-Nachrichten empfangen.

Felder
audio_data

bytes

Nur Ausgabe: Die Audiodaten, die die Antwort des Assistenten auf die Anfrage enthalten. Sequenzielle Blöcke von Audiodaten werden in aufeinanderfolgenden ConverseResponse-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.

ConverseConfig

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

Felder
audio_in_config

AudioInConfig

Erforderlich: Gibt an, wie die nachfolgend eingehenden Audiodaten verarbeitet werden.

audio_out_config

AudioOutConfig

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

converse_state

ConverseState

Erforderlich. Gibt den aktuellen Status des Dialogfelds an.

ConverseRequest

Die vom Client gesendete Nachricht der obersten Ebene. Clients müssen mindestens zwei, in der Regel zahlreiche ConverseRequest-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 converse_request. In jeder ConverseRequest muss genau eines dieser Felder angegeben werden. Für converse_request ist nur einer der folgenden Werte zulässig:
config

ConverseConfig

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

audio_in

bytes

Die zu erkennenden Audiodaten. Sequenzielle Blöcke von Audiodaten werden in sequenziellen ConverseRequest-Nachrichten gesendet. Die erste ConverseRequest-Nachricht darf keine audio_in-Daten enthalten, alle nachfolgenden ConverseRequest-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.

ConverseResponse

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

Felder
Union-Feld converse_response. Genau eines dieser Felder wird in jeder ConverseResponse ausgefüllt. Für converse_response ist nur einer der folgenden Werte zulässig:
error

Status

Nur Ausgabe. Wenn festgelegt, wird eine google.rpc.Status-Meldung zurückgegeben, die den Fehler für den Vorgang angibt. Wenn während der Verarbeitung ein Fehler auftritt, wird diese Meldung festgelegt und es werden keine weiteren Nachrichten gesendet.

event_type

EventType

Nur Ausgabe Gibt den Ereignistyp an.

audio_out

AudioOut

Nur Ausgabe. Die Audiodatei mit der Antwort des Assistenten auf die Anfrage.

result

ConverseResult

Nur Ausgabe. Das semantische Ergebnis für die vom Nutzer gesprochene Suchanfrage.

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.

ConverseResult

Das semantische Ergebnis der gesprochenen Suchanfrage des Nutzers.

Felder
spoken_request_text

string

Nur Ausgabe. Das erkannte Transkript dessen, was der Nutzer gesagt hat.

spoken_response_text

string

Nur Ausgabe. Der Text der gesprochenen Antwort des Assistenten. Dies wird nur bei einer IFTTT-Aktion zurückgegeben.

conversation_state

bytes

Nur Ausgabe: Statusinformationen für nachfolgende ConverseRequest. Dieser Wert sollte im Client gespeichert und im conversation_state mit dem nächsten ConverseRequest zurückgegeben werden. Der Client muss diesen Wert nicht interpretieren oder anderweitig verwenden. Diese Informationen müssen bei einem Geräteneustart nicht gespeichert werden.

microphone_mode

MicrophoneMode

Nur Ausgabe: Gibt den Mikrofonmodus an, nachdem dieser Converse-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 dem neuen Lautstärkepegel 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 ConverseRequest 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 Converse-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 Converse-RPC-Aufruf zum Senden der neuen Audiodaten gestartet.

ConverseState

Liefert Informationen zum aktuellen Dialogstatus.

Felder
conversation_state

bytes

Erforderlich. Der im vorherigen ConverseResponse zurückgegebene conversation_state-Wert. Lassen Sie den Wert aus (Feld nicht festlegen), wenn es vorher keine ConverseResponse gab. Wenn es vorher eine ConverseResponse gab, lassen Sie dieses Feld nicht weg. Dadurch wird die Unterhaltung beendet und mit der neuen Anfrage wird eine neue Unterhaltung gestartet.