Package google.assistant.embedded.v1alpha2

Index

EmbeddedAssistant

Service qui implémente l'API Assistant Google.

Passe décisive

rpc Assist(AssistRequest) returns (AssistResponse)

Lance ou poursuit une conversation avec le service Assistant intégré. Chaque appel effectue un aller-retour, en envoyant une requête audio au service et en recevant la réponse audio. Utilise le streaming bidirectionnel pour recevoir des résultats, tels que l'événement END_OF_UTTERANCE, tout en envoyant du contenu audio.

Une conversation correspond à une ou plusieurs connexions gRPC, chacune composée de plusieurs requêtes et réponses diffusées. Par exemple, il dit Ajouter à ma liste de courses et l'Assistant répond Que voulez-vous ajouter ? La séquence de requêtes et de réponses diffusées dans le premier message gRPC peut se présenter comme suit:

  • AssistRequest.config
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistRequest.audio_in
  • AssistResponse.event_type.END_OF_UTTERANCE
  • AssistResponse.Speech_results.transcript "ajouter à ma liste de courses"
  • AssistResponse.dialog_state_out.microphone_mode.DIALOG_FOLLOW_ON
  • AssistResponse.audio_out
  • AssistResponse.audio_out
  • AssistResponse.audio_out

L'utilisateur dit ensuite bagels, et l'Assistant répond OK, j'ai ajouté des bagels à votre liste de courses. Il est envoyé via un autre appel de connexion gRPC à la méthode Assist, là encore avec des requêtes et des réponses diffusées en streaming, par exemple:

  • 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

Bien que l'ordre précis des réponses ne soit pas garanti, les messages AssistResponse.audio_out séquentiels contiendront toujours des parties audio séquentielles.

Champs d'application des autorisations

Requiert le champ d'application OAuth suivant :

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

Pour en savoir plus, consultez le guide d'authentification.

AssistConfig

Indique comment traiter les messages AssistRequest.

Champs
audio_out_config

AudioOutConfig

Obligatoire : spécifie le format du contenu audio renvoyé.

screen_out_config

ScreenOutConfig

Facultatif. Spécifie le format à utiliser lorsque le serveur renvoie une réponse d'écran visuelle.

dialog_state_in

DialogStateIn

Obligatoire. Représente l'état actuel de la boîte de dialogue.

device_config

DeviceConfig

Configuration qui identifie un appareil spécifique de manière unique.

debug_config

DebugConfig

Facultatif. Paramètres de débogage de l'ensemble du RPC Assist.

Champ d'union type.

type ne peut être qu'un des éléments suivants :
audio_in_config

AudioInConfig

Spécifie comment traiter le son entrant suivant. Obligatoire si AssistRequest.audio_in octets sont fournis dans les requêtes ultérieures.

text_query

string

Texte à envoyer à l'Assistant. Il peut être renseigné à partir d'une interface de texte si l'entrée audio n'est pas disponible.

AssistRequest

Message de premier niveau envoyé par le client. Les clients doivent envoyer au moins deux messages AssistRequest, et généralement de nombreux. Le premier message doit contenir un message config et ne doit pas contenir de données audio_in. Tous les messages suivants doivent contenir des données audio_in et pas de message config.

Champs
Champ d'union type. Un seul de ces champs doit être spécifié dans chaque AssistRequest. La type ne peut être qu'un des éléments suivants :
config

AssistConfig

Le message config fournit à l'outil de reconnaissance des informations qui spécifient comment traiter la requête. Le premier message AssistRequest doit contenir un message config.

audio_in

bytes

Données audio à reconnaître. Des blocs séquentiels de données audio sont envoyés dans des messages AssistRequest séquentiels. Le premier message AssistRequest ne doit pas contenir de données audio_in et tous les messages AssistRequest suivants doivent contenir des données audio_in. Les octets de données audio doivent être encodés comme spécifié dans AudioInConfig. Le son doit être envoyé en temps quasi réel (16 000 échantillons par seconde). Une erreur est renvoyée si le contenu audio est envoyé beaucoup plus rapidement ou plus lentement.

AssistResponse

Message de premier niveau reçu par le client. Une série d'un ou de plusieurs messages AssistResponse est diffusée en streaming vers le client.

Champs
event_type

EventType

Uniquement en sortie : indique le type d'événement.

audio_out

AudioOut

Sortie uniquement : contenu audio contenant la réponse de l'Assistant à la requête.

screen_out

ScreenOut

Sortie uniquement : contient la réponse visuelle de l'Assistant à la requête.

device_action

DeviceAction

Sortie uniquement : contient l'action déclenchée par la requête avec les charges utiles et l'analyse sémantique appropriées.

speech_results[]

SpeechRecognitionResult

Sortie uniquement : cette liste répétée contient zéro, un ou plusieurs résultats de reconnaissance vocale correspondant à des parties consécutives de l'audio en cours de traitement, en commençant par la partie correspondant au contenu audio le plus ancien (et la partie la plus stable) à la partie correspondant au contenu audio le plus récent. Les chaînes peuvent être concaténées pour afficher la réponse en cours complète. Une fois la reconnaissance vocale terminée, cette liste contient un élément avec stability défini sur 1.0.

dialog_state_out

DialogStateOut

Sortie uniquement : contient la sortie liée à la requête de l'utilisateur.

debug_info

DebugInfo

Uniquement en sortie : informations de débogage destinées aux développeurs. N'est renvoyé que si la requête définit return_debug_info sur "true".

EventType

Indique le type d'événement.

Enums
EVENT_TYPE_UNSPECIFIED Aucun événement spécifié.
END_OF_UTTERANCE Cet événement indique que le serveur a détecté la fin de l'énoncé de l'utilisateur et ne s'attend plus à aucune entrée vocale. Le serveur ne traite donc pas de nouvelles données audio (bien qu'il puisse par la suite renvoyer des résultats supplémentaires). Le client doit arrêter d'envoyer des données audio, interrompre à moitié la connexion gRPC, et attendre les résultats supplémentaires jusqu'à ce que le serveur stoppe cette connexion.

AudioInConfig

Spécifie comment traiter les données audio_in qui seront fournies dans les requêtes ultérieures. Pour connaître les paramètres recommandés, consultez les bonnes pratiques concernant le SDK de l'Assistant Google.

Champs
encoding

Encoding

Obligatoire : encodage des données audio envoyées dans tous les messages audio_in.

sample_rate_hertz

int32

Obligatoire : Taux d'échantillonnage (en Hertz) des données audio envoyées dans tous les messages audio_in. Les valeurs valides sont comprises entre 16 000 et 24 000, mais 16 000 est optimal. Pour de meilleurs résultats, définissez le taux d'échantillonnage de la source audio sur 16 000 Hz. Si ce n'est pas possible, utilisez le taux d'échantillonnage natif de la source audio (plutôt que d'effectuer un ré-échantillonnage).

Encodage

Encodage audio des données envoyées dans le message audio. L'audio doit être à un seul canal (mono).

Enums
ENCODING_UNSPECIFIED Non spécifié. Renvoie le résultat google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Échantillons little-endian de 16 bits signés et non compressés (LPCM). Cet encodage n'inclut pas d'en-tête, mais uniquement les octets audio bruts.
FLAC L'encodage FLAC (Free Lossless Audio Codec, codec audio sans perte sans frais) est recommandé, car il est sans perte. De ce fait, la reconnaissance n'est pas compromise et ne nécessite qu'environ la moitié de la bande passante par rapport à LINEAR16. Cet encodage inclut l'en-tête de flux FLAC suivi des données audio. Il accepte les échantillons 16 bits et 24 bits. Toutefois, tous les champs de STREAMINFO ne sont pas acceptés.

AudioOut

Audio contenant la réponse de l'Assistant à la requête. Des fragments séquentiels de données audio sont reçus dans des messages AssistResponse séquentiels.

Champs
audio_data

bytes

Sortie uniquement : données audio contenant la réponse de l'Assistant à la requête. Des fragments séquentiels de données audio sont reçus dans des messages AssistResponse séquentiels.

AudioOutConfig

Spécifie le format que le serveur doit utiliser lorsqu'il renvoie des messages audio_out.

Champs
encoding

Encoding

Obligatoire. Encodage des données audio à renvoyer dans tous les messages audio_out.

sample_rate_hertz

int32

Obligatoire. Taux d'échantillonnage en Hertz des données audio renvoyées dans les messages audio_out. Les valeurs possibles sont comprises entre 16 000 et 24 000.

volume_percentage

int32

Obligatoire. Paramètre de volume actuel de la sortie audio de l'appareil. Les valeurs valides sont comprises entre 1 et 100 (correspondant à 1% et 100%).

Encodage

Encodage audio des données renvoyées dans le message audio. Tous les encodages sont des octets audio bruts sans en-tête, sauf indication contraire ci-dessous.

Enums
ENCODING_UNSPECIFIED Non spécifié. Renvoie le résultat google.rpc.Code.INVALID_ARGUMENT.
LINEAR16 Échantillons little-endian de 16 bits signés et non compressés (LPCM).
MP3 Encodage audio MP3. Le taux d'échantillonnage est encodé dans la charge utile.
OPUS_IN_OGG Audio encodé au format Opus et encapsulé dans un conteneur Ogg. Vous obtiendrez un fichier qui pourra être lu de manière native sur Android et dans certains navigateurs (comme Chrome). La qualité de l'encodage est considérablement supérieure à celle du format MP3 tout en utilisant le même débit. Le taux d'échantillonnage est encodé dans la charge utile.

DebugConfig

Paramètres de débogage de la requête actuelle.

Champs
return_debug_info

bool

Lorsque ce champ est défini sur "true", le champ debug_info de AssistResponse peut être renseigné. Cependant, cela augmente considérablement la latence des réponses.

DebugInfo

Informations de débogage pour le développeur. N'est renvoyé que si la requête définit return_debug_info sur "true".

Champs
aog_agent_to_assistant_json

string

Réponse JSON d'origine d'un agent Action-on-Google envoyée au serveur Google. Consultez AppResponse. Il n'est renseigné que si le créateur de la requête est propriétaire du projet AoG et que ce projet est en mode aperçu.

DeviceAction

Réponse renvoyée à l'appareil si l'utilisateur a déclenché une action sur l'appareil. Par exemple, un appareil qui prend en charge la requête Turn on the light (Allumer la lumière) recevrait une réponse DeviceAction avec une charge utile JSON contenant la sémantique de la requête.

Champs
device_request_json

string

JSON contenant la réponse de la commande d'appareil générée à partir de la grammaire déclenchée par l'action sur l'appareil. Le format est fourni par l'intent action.devices.EXECUTE pour une caractéristique donnée.

DeviceConfig

Champs obligatoires permettant à l'Assistant d'identifier l'appareil.

Voir également :

Champs
device_id

string

Obligatoire Identifiant unique de l'appareil. L'ID ne doit pas comporter plus de 128 caractères. Exemple: DBCDW098234. Il DOIT correspondre à l'identifiant device_id renvoyé lors de l'enregistrement de l'appareil. Cet device_id permet d'établir une correspondance avec les appareils enregistrés de l'utilisateur afin de rechercher les caractéristiques et les fonctionnalités compatibles de cet appareil. Ces informations ne doivent pas changer lors des redémarrages de l'appareil. Toutefois, il ne doit pas être enregistré lors du rétablissement de la configuration d'usine.

device_model_id

string

Obligatoire Identifiant unique du modèle de l'appareil. La combinaison de device_model_id et device_id doit avoir été précédemment associée lors de l'enregistrement de l'appareil.

DeviceLocation

Il existe trois sources de localisation. Ils sont utilisés avec cette priorité:

  1. Ce DeviceLocation, qui est principalement utilisé pour les appareils mobiles équipés d'un GPS .
  2. Lieu spécifié par l'utilisateur lors de la configuration de l'appareil (par utilisateur et par appareil). Cet emplacement est utilisé si DeviceLocation n'est pas spécifié.
  3. Localisation déduite en fonction de l'adresse IP. Cette option n'est utilisée que si aucune des options ci-dessus n'est spécifiée.
Champs
coordinates

LatLng

Latitude et longitude de l'appareil.

DialogStateIn

Fournit des informations sur l'état actuel de la boîte de dialogue.

Champs
conversation_state

bytes

Required (Obligatoire) Ce champ doit toujours être défini sur la valeur DialogStateOut.conversation_state renvoyée lors du RPC Assist précédent. Ce champ ne doit être omis (champ non défini) que s'il n'y a pas eu de RPC Assist antérieur, car il s'agit du premier RPC Assist effectué par cet appareil après sa première configuration et/ou une réinitialisation par défaut.

language_code

string

Obligatoire Langue de la requête dans la syntaxe de l'IETF BCP 47 (par exemple, "en-US"). Pour en savoir plus, consultez la page Langues acceptées. Si vous avez sélectionné une langue pour votre device_id via le menu Paramètres de l'application Assistant Google de votre téléphone, cette sélection remplacera cette valeur.

device_location

DeviceLocation

Facultatif. Emplacement de l'appareil d'où provient la requête.

is_new_conversation

bool

Facultatif. Si la valeur est "true", le serveur traite la requête comme une nouvelle conversation et n'utilise pas l'état de la requête précédente. Définissez ce champ sur "true" lorsque la conversation doit redémarrer (par exemple, après un redémarrage de l'appareil ou après un laps de temps significatif depuis la requête précédente).

DialogStateOut

État de la boîte de dialogue résultant de la requête de l'utilisateur. Plusieurs de ces messages peuvent être reçus.

Champs
supplemental_display_text

string

Texte supplémentaire de l'Assistant pour l'affichage uniquement en sortie. Il peut s'agir de la voix prononcée en AssistResponse.audio_out ou d'informations supplémentaires pour aider l'utilisateur à comprendre.

conversation_state

bytes

Informations d'état en sortie uniquement pour le RPC Assist suivant. Cette valeur doit être enregistrée dans le client et renvoyée dans le champ DialogStateIn.conversation_state avec le RPC Assist suivant. (Le client n'a pas besoin d'interpréter ni d'utiliser cette valeur.) Ces informations doivent être enregistrées à chaque redémarrage de l'appareil. Toutefois, cette valeur doit être effacée (et non enregistrée dans le client) lors d'une réinitialisation aux paramètres d'usine.

microphone_mode

MicrophoneMode

Sortie uniquement Spécifie le mode du micro après le traitement de ce RPC Assist.

volume_percentage

int32

Sortie uniquement Mise à jour du niveau de volume. La valeur est égale à 0 ou omise (indiquant qu'elle ne change rien), sauf si une commande vocale telle que Augmenter le volume ou Régler le niveau de volume 4 a été reconnue. Dans ce cas, elle est comprise entre 1 et 100 (correspondant au nouveau niveau de volume compris entre 1% et 100%). En règle générale, le client doit utiliser ce niveau de volume lors de la lecture des données audio_out, conserver cette valeur comme niveau de volume actuel et la fournir dans la AudioOutConfig du AssistRequest suivant. (Certains clients peuvent également mettre en œuvre d'autres moyens pour permettre la modification du niveau de volume actuel, par exemple en fournissant un bouton que l'utilisateur peut tourner.)

MicrophoneMode

États possibles du micro une fois un RPC Assist terminé.

Enums
MICROPHONE_MODE_UNSPECIFIED Aucun mode spécifié.
CLOSE_MICROPHONE Le service n'attend pas de question complémentaire de la part de l'utilisateur. Le micro doit rester désactivé jusqu'à ce que l'utilisateur le réactive.
DIALOG_FOLLOW_ON Le service attend une question complémentaire de la part de l'utilisateur. Le micro doit être rouvert à la fin de la lecture du AudioOut (en démarrant un nouvel appel RPC Assist pour envoyer le nouveau contenu audio).

ScreenOut

Réponse visuelle de l'Assistant à la requête. Activée par screen_out_config.

Champs
format

Format

Sortie uniquement : format des données d'écran fournies.

data

bytes

Sortie uniquement : données brutes de l'écran à afficher en réponse à la requête de l'Assistant.

Format

Formats possibles des données de l'écran.

Enums
FORMAT_UNSPECIFIED Aucun format spécifié.
HTML Les données contiendront une mise en page HTML5 complète et encodée au format UTF-8 (par exemple, <html><body><div>...</div></body></html>). Elle est destinée à être rendue avec la réponse audio. Notez que l'attribut doctype HTML5 doit être inclus dans les données HTML réelles.

ScreenOutConfig

Spécifie le format que le serveur doit utiliser lorsqu'il renvoie la réponse screen_out.

Champs
screen_mode

ScreenMode

Mode d'écran visuel actuel pour l'appareil lors de l'émission de la requête.

ScreenMode

Modes possibles pour la sortie d'écran visuelle sur l'appareil.

Enums
SCREEN_MODE_UNSPECIFIED Aucun mode vidéo spécifié. L'Assistant peut répondre comme s'il était en mode OFF.
OFF L'écran est éteint (ou sa luminosité ou d'autres paramètres sont réglés sur une valeur faible pour qu'il ne soit pas visible). Dans ce mode, l'Assistant n'affiche généralement pas de réponse.
PLAYING Dans ce mode, l'Assistant affiche généralement une réponse affichée sur une partie de l'écran.

SpeechRecognitionResult

Transcription estimée d'une phrase que l'utilisateur a prononcée. Il peut s'agir d'un seul segment ou de la proposition complète de la requête vocale de l'utilisateur.

Champs
transcript

string

Uniquement en sortie : texte de transcription représentant les mots prononcés par l'utilisateur.

stability

float

Uniquement en sortie : estimation de la probabilité que l'Assistant ne modifie pas son hypothèse concernant ce résultat. Les valeurs vont de 0.0 (complètement instable) à 1.0 (complètement stable et finale). La valeur par défaut de 0,0 est une valeur sentinelle indiquant que stability n'a pas été défini.