Blog • App Intents

Comment un agent iOS 27 appelle une app tierce : valider le JSON de l'App Intent avant l'API

Quand le système appelle une app tierce, l'entrée est l'AppIntent que vous déclarez. Après l'arrivée des paramètres dans perform() et avant l'API, écrivez-les en JSON. Si le type, l'enum ou une clé requise ne correspond pas, renvoyez un enregistrement d'échec et arrêtez dans l'app.

Comment une demande atteint une API : le chemin JSON d'une App Action. Siri deviendra-t-elle un agent : Siri AI deviendra-t-elle un agent IA. Cet article ne traite que le côté app : quels paramètres déclarer, ce que le schéma arrête, et quel JSON renvoyer en cas d'échec.

• Les paramètres de l'Intent sont le contrat de l'app
• Le schéma vérifie le type, l'enum et les clés requises
• Un échec s'enregistre en needs_value ou rejected
• Aucun de ces deux enregistrements n'atteint l'API

Déclarer d'abord le contrat des paramètres

L'entrée de l'app tierce est un AppIntent. Vous lui donnez un titre et implémentez perform(). Le système découvre l'action parce que vous l'avez déclarée. La déclaration ne prouve pas que ces paramètres peuvent appeler l'API.

Marquez chaque paramètre avec @Parameter. Voir Ajouter des paramètres à un App Intent. Cet exemple n'accepte que trois choses : un id d'article, une quantité et un mode de remise. Les noms, le texte explicatif et les clés ajoutées par un modèle ne sont pas dans le contrat.

1. 1
   Fixer le nom de l'Intent

   Le champ intent du JSON candidat ne peut être que PlaceOrderIntent. Un autre nom signifie que l'appel a trouvé la mauvaise action.

2. 2
   Lister les trois paramètres

   itemId est une chaîne, quantity un entier, fulfillment seulement pickup ou delivery. S'il en manque un, le candidat est incomplet.

3. 3
   Valider au début de perform()

   Si la validation échoue, renvoyez l'enregistrement d'échec ci-dessous. Appelez l'API seulement après succès, résolution de l'id et quantité d'au moins 1.

Écrire les mêmes champs en schéma

Le candidat et le schéma ci-dessous sont votre contrat, pas le format réseau d'Apple. JSON Schema dans JSONNote vérifie les types, les enums et les clés requises. Il ne peut pas dire que la quantité doit valoir au moins 1 ni que l'id doit exister. Ces décisions restent dans l'app.

{
  "intent": "PlaceOrderIntent",
  "parameters": {
    "itemId": "sku_42",
    "quantity": 1,
    "fulfillment": "pickup"
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["intent", "parameters"],
  "properties": {
    "intent": { "enum": ["PlaceOrderIntent"] },
    "parameters": {
      "type": "object",
      "required": ["itemId", "quantity", "fulfillment"],
      "properties": {
        "itemId": { "type": "string" },
        "quantity": { "type": "integer" },
        "fulfillment": { "enum": ["pickup", "delivery"] }
      }
    }
  }
}

Comment les types de paramètres s'alignent : champs d'action de l'app et JSON Schema. Cet article ne répète pas ce tableau. Il décrit seulement ce que l'app renvoie quand la validation échoue.

Trois candidats qui échouent

Mettez quantity à 0 : le type reste un entier, donc ce schéma passe. Réussir n'est pas une commande. L'app doit refuser une quantité de 0.

Une forme valide peut quand même s'arrêter

{
  "intent": "PlaceOrderIntent",
  "status": "rejected",
  "reason": "invalid_parameter",
  "field": "quantity",
  "dialog": "Quantity must be at least 1."
}

Un itemId non vide passe aussi le schéma. Résolvez ensuite cet id dans vos propres données. S'il ne se résout pas, écrivez un autre rejected avec field égal à itemId. N'inventez pas un id à partir d'un nom de produit, et n'appelez pas l'API.

Comment l'échec revient

S'il manque une valeur requise, redemandez-la avec requestValue sur ce paramètre. N'appelez pas l'API avec une valeur vide. Si une valeur est illégale, arrêtez perform() et utilisez IntentDialog pour écrire la phrase que la personne peut lire. Le JSON ci-dessus est l'enregistrement que vous gardez pour cette décision.

needs_value signifie qu'il faut encore demander. rejected signifie que ce candidat ne peut pas s'exécuter. Aucun des deux n'atteint l'API. La personne voit la phrase dialog. Le journal garde tout le JSON pour retrouver plus tard quel champ a arrêté l'appel.

Ce que les autres articles couvrent

Arrêter l'appel dans JSONNote

1. 1
   Choisir la bonne opération

   Ouvrez JSON Schema. Réglez Fonctionnement sur Vérifiez avec Schema. Collez le candidat dans le premier champ et le schéma ci-dessus dans le second. intent ne peut être que PlaceOrderIntent. fulfillment seulement pickup ou delivery. quantity doit être un entier.

2. 2
   Opposer trois documents invalides

   Mettez fulfillment à ship, quantity à la chaîne 1, ou supprimez itemId. Les trois échouent. quantity à 0 passe. Après ce succès, écrivez quand même rejected et n'appelez pas l'API.

3. 3
   Comparer 1 et 0

   Ouvrez JSON Comparer Diff. Collez parameters avec quantity 1 dans le premier champ, et le même objet avec quantity 0 dans le second. La différence est ce nombre. 0 passe encore le schéma. C'est l'enregistrement d'échec qui arrête l'API, pas ce contrôle de forme.

Questions fréquentes

Si le système a déjà remis les paramètres à l'app, validez-vous encore ?

Oui. Le système a remis un appel, pas une requête API déjà vérifiée. Au début de perform(), lisez ce JSON. S'il ne passe pas, ne continuez pas.

Peut-on appeler l'API dès que le schéma passe ?

Pas encore. Ce schéma ne vérifie que le type, l'enum et les clés requises. quantity 0 passe. Un itemId chaîne passe aussi. Appelez l'API seulement si la quantité vaut au moins 1 et si l'id se résout.

S'il manque un paramètre, renvoyez-vous une erreur ou redemandez-vous ?

Redemandez. Mettez status à needs_value et utilisez requestValue pour demander cette valeur. N'appelez pas l'API avant d'avoir une valeur légale. Si la valeur arrive et qu'elle est illégale, écrivez rejected.

Est-ce le même article que le chemin JSON d'une demande ?

Non. Cet article suit une demande de la phrase à l'API. Celui-ci reste dans l'app : le contrat des paramètres, le schéma et le JSON renvoyé en cas d'échec. L'API ne tourne que si ni rejected ni needs_value n'a été écrit.

L'enregistrement d'échec est-il le format de réponse d'Apple ?

Non. Apple remet le résultat au système et à la personne avec requestValue et IntentDialog. Ce JSON est votre propre journal : status, reason, field, dialog. Gardez-le pour revoir dans JSONNote pourquoi l'API n'a pas été appelée.

Conclusion

Quand une app tierce est appelée, il y a d'abord un contrat de paramètres, puis un JSON qui a le droit d'échouer. L'enregistrement d'échec arrête l'appel avant l'API et garde une phrase dialog lisible.

La décision : déclarer d'abord les paramètres de l'Intent ; le schéma arrête les mauvais types, enums et clés requises manquantes ; needs_value si une valeur manque ; rejected si une valeur est illégale ; aucun des deux n'appelle l'API ; une quantité inférieure à 1 ou un id introuvable arrête aussi une forme valide.

Retour au blog