Votre appareil peut avoir des capacités spéciales qui ne sont pas couvertes par l'ensemble actuel decaractéristiques . Par exemple, un trait "clignoter ma lumière" pour un appareil qui peut clignoter. Vous pouvez définir des actions personnalisées pour votre appareil qui spécifient les commandes envoyées à votre appareil pour déclencher des fonctionnalités spéciales.
Pour définir une action personnalisée sur un appareil, vous avez besoin des éléments suivants:
- Un modèle à mettre en correspondance avec la requête de l'utilisateur
- Action personnalisée sur un appareil à associer à une requête correspondante
- Texte énoncé à l'utilisateur si l'appareil est compatible avec l'action
- Un nom de commande renvoyé à votre appareil, avec tous les paramètres
Pour créer l'action personnalisée sur l'appareil, vous devez placer ces informations dans un package d'actions. Les packages d'actions définissent le format des réponses de l'Assistant. Contrairement au SDK Actions, les actions personnalisées sur les appareils sont exécutées localement. Vous ne spécifiez pas de point de terminaison pour traiter les requêtes et fournir des réponses. Les actions personnalisées sur les appareils ne sont pas de nature conversationnelle.
Créer un package d'actions
À l'aide de l'exemple suivant, créez un fichier (tel que actions.json) qui définit une commande de test: faire clignoter un voyant.
Copiez-le à partir de l'exemple de code que vous avez téléchargé à l'étape précédente:
cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/grpc/
cp ~/assistant-sdk-python/google-assistant-sdk/actions.json .
{
"manifest": {
"displayName": "Blinky light",
"invocationName": "Blinky light",
"category": "PRODUCTIVITY"
},
"actions": [
{
"name": "com.example.actions.BlinkLight",
"availability": {
"deviceClasses": [
{
"assistantSdkDevice": {}
}
]
},
"intent": {
"name": "com.example.intents.BlinkLight",
"parameters": [
{
"name": "number",
"type": "SchemaOrg_Number"
},
{
"name": "speed",
"type": "Speed"
}
],
"trigger": {
"queryPatterns": [
"blink ($Speed:speed)? $SchemaOrg_Number:number times",
"blink $SchemaOrg_Number:number times ($Speed:speed)?"
]
}
},
"fulfillment": {
"staticFulfillment": {
"templatedResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Blinking $number times"
}
},
{
"deviceExecution": {
"command": "com.example.commands.BlinkLight",
"params": {
"speed": "$speed",
"number": "$number"
}
}
}
]
}
}
}
}
],
"types": [
{
"name": "$Speed",
"entities": [
{
"key": "SLOWLY",
"synonyms": [
"slowly",
"slow"
]
},
{
"key": "NORMALLY",
"synonyms": [
"normally",
"regular"
]
},
{
"key": "QUICKLY",
"synonyms": [
"quickly",
"fast",
"quick"
]
}
]
}
]
}
L'exemple précédent utilise les informations suivantes pour définir l'action personnalisée sur l'appareil:
- Un schéma à mettre en correspondance avec la requête de l'utilisateur (clignotement N fois)
- Action personnalisée sur l'appareil à associer à une requête correspondante (
com.example.actions.BlinkLight) à des fins organisationnelles - Texte énoncé à l'utilisateur si l'appareil est compatible avec l'action (Clignotant N fois)
- Un nom de commande (
com.example.commands.BlinkLight) renvoyé à l'appareil, avec tous les paramètres (un nombre et éventuellement une description de la vitesse)
Pour définir le modèle de requête, tenez compte des points suivants:
- Vous pouvez utiliser des types définis par schema.org dans le schéma de requête.
- Le tableau
types [...]définit la liste des types personnalisés (par exemple,$Speed). - Vous pouvez utiliser des types personnalisés dans le schéma de requête. L'utilisateur peut prononcer n'importe lequel des synonymes de votre type personnalisé pour correspondre au schéma de requête.
- Lorsqu'un synonyme correspond, l'instance de type (
speed) renvoie la clé normalisée (SLOWLY). Plusieurs entités peuvent être utilisées. Par exemple, différents voyants acceptent différentes vitesses de clignotement. - Certaines parties du schéma de synthèse vocale de la requête peuvent être facultatives. Par exemple, utilisez
($Speed:speed)?dans le schéma de requête pour rendre cette partie facultative. - Dans la synthèse vocale de la réponse,
$type.raw(par exemple,$speed.raw) est remplacé par le ou les mots que l'utilisateur a réellement prononcés.
Pour obtenir une description de la plupart de ces champs, consultez la documentation d'ActionPackage.
Déployer le package d'actions
Après avoir créé une action personnalisée sur votre appareil dans un package d'actions, vous pouvez rendre le package d'actions accessible à l'Assistant.
Vous pouvez effectuer les étapes de cette section sur votre appareil, mais il peut être plus simple de les effectuer sur votre système de développement. L'exécution des commandes suivantes ne nécessite pas d'environnement virtuel.
Téléchargez l'outil de ligne de commande
gactions.Supprimez tous les identifiants existants du même répertoire que l'outil
gactions.rm creds.data
Enregistrez votre package d'actions sur Google à l'aide de la CLI
gactions. Remplacezproject_idpar l'ID de votre projet dans la console Actions../gactions update --action_package actions.json --project project_id
La première fois que vous exécutez cette commande, vous obtenez une URL et vous êtes invité à vous connecter. Copiez l'URL, puis collez-la dans un navigateur (cela peut être fait sur n'importe quel système). Vous êtes alors invité à vous connecter à votre compte Google. Connectez-vous au compte Google avec lequel vous avez créé le projet à une étape précédente étape.
Une fois que vous avez approuvé la demande d'autorisation de l'API, un code s'affiche dans votre navigateur, par exemple "4/XXXX". Copiez et collez ce code dans le terminal:
Enter the authorization code:
Si l'autorisation a abouti, une réponse semblable à la suivante s'affiche:
Your app for the Assistant for project my-devices-project was successfully updated with your actions.Déployez votre package d'actions en mode test à l'aide de la CLI
gactions. Vous devez avoir enregistré votre package d'actions sur Google au moins une fois avant d'exécuter cette commande. Le mode test n'active le package d'actions que sur votre compte utilisateur../gactions test --action_package actions.json --project project_id
Actuellement, vous ne pouvez pas tester le projet à l'aide du simulateur Actions.
Pour mettre à jour le package d'actions, utilisez la commande
gactions update.(Facultatif) Vous pouvez créer des packages d'actions localisés pour prendre en charge différentes langues et paramètres régionaux à la fois dans un même projet.
Modifier l'exemple
Suivez les étapes décrites dans cette section sur l'appareil.
nano pushtotalk.py
Ajoutez un gestionnaire pour votre action personnalisée. Notez que le gestionnaire ci-dessous a déjà été ajouté à l'exemple de code pour l'exemple de package d'actions ci-dessus.
...
device_handler = device_helpers.DeviceRequestHandler(device_id)
@device_handler.command('com.example.commands.BlinkLight')
def blink(speed, number):
logging.info('Blinking device %s times.' % number)
delay = 1
if speed == "SLOWLY":
delay = 2
elif speed == "QUICKLY":
delay = 0.5
for i in range(int(number)):
logging.info('Device is blinking.')
# GPIO.output(25, 1)
time.sleep(delay)
# GPIO.output(25, 0)
time.sleep(1)
Exécuter l'exemple
Exécutez le code source.
python pushtotalk.py
Essayez une requête. Pour l'exemple ci-dessus, essayez ce qui suit:
Clignotez cinq fois.
Notez que la requête doit correspondre au format de requête du package d'actions.