Blog • App Intents

Wie ein iOS-27-Agent eine Drittanbieter-App aufruft: App-Intent-JSON vor der API prüfen

Ruft das System eine Drittanbieter-App auf, ist der Eingang der von Ihnen deklarierte AppIntent. Nachdem die Parameter perform() erreichen und bevor eine API läuft, schreiben Sie sie als JSON. Passen Typ, Enum oder ein Pflichtfeld nicht, geben Sie einen Fehlereintrag zurück und stoppen in der App.

Wie ein Auftrag eine API erreicht, steht in den JSON-Pfad einer App Action. Ob Siri ein Agent wird, steht in Wird Siri AI ein KI-Agent. Dieser Artikel ist nur die App-Seite: welche Parameter Sie deklarieren, was das Schema stoppt, und welches JSON Sie bei einem Fehler zurückgeben.

• Intent-Parameter sind der eigene Vertrag der App
• Das Schema prüft Typ, Enum und Pflichtfelder
• Ein Fehler wird als needs_value oder rejected festgehalten
• Keine der beiden Aufzeichnungen erreicht die API

Zuerst den Parametervertrag deklarieren

Der Eingang der Drittanbieter-App ist ein AppIntent. Sie geben einen Titel und implementieren perform(). Das System findet die Aktion, weil Sie sie deklariert haben. Die Deklaration beweist nicht, dass diese Parameter die API aufrufen dürfen.

Jedes Parameter markieren Sie mit @Parameter. Siehe Parameter zu einem App Intent hinzufügen. Dieses Beispiel nimmt nur drei Dinge: Artikel-Id, Menge, Erfüllung. Namen, Erklärungstext und zusätzliche Schlüssel eines Modells stehen nicht im Vertrag.

1. 1
   Den Intent-Namen festnageln

   Das Feld intent im Kandidaten-JSON darf nur PlaceOrderIntent sein. Jeder andere Name heißt: dieser Aufruf hat die falsche Aktion gefunden.

2. 2
   Die drei Parameter auflisten

   itemId ist eine Zeichenkette, quantity eine Ganzzahl, fulfillment nur pickup oder delivery. Fehlt eines, ist der Kandidat unvollständig.

3. 3
   Am Anfang von perform() prüfen

   Schlägt die Prüfung fehl, geben Sie den Fehlereintrag unten zurück. Erst wenn sie besteht, die Id sich auflöst und die Menge mindestens 1 ist, geht es zur API.

Dieselben Felder als Schema schreiben

Kandidat und Schema unten sind Ihr Vertrag, nicht Apples Leitungsformat. JSON Schema in JSONNote prüft Typen, Enums und Pflichtfelder. Dass die Menge mindestens 1 sein muss und die Id existieren muss, drückt dieses Schema nicht aus. Das entscheidet die 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"] }
      }
    }
  }
}

Wie Parametertypen zusammenpassen, steht in Aktionsfelder der App und JSON Schema. Diese Tabelle wiederholt der Artikel nicht. Er beschreibt nur, was die App zurückgibt, wenn die Prüfung scheitert.

Drei Kandidaten, die scheitern

Setzen Sie quantity auf 0: der Typ bleibt eine Ganzzahl, das Schema besteht. Bestehen ist keine Bestellung. Die Menge 0 muss die App ablehnen.

Gültige Form kann trotzdem stoppen

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

Eine nicht leere itemId besteht das Schema ebenfalls. Lösen Sie diese Id danach in Ihren eigenen Daten auf. Gelingt das nicht, schreiben Sie einen weiteren rejected-Eintrag mit field itemId. Erfinden Sie keine Id aus einem Produktnamen und rufen Sie die API nicht auf.

Wie der Fehler zurückgeht

Fehlt ein Pflichtwert, fragen Sie mit requestValue an diesem Parameter noch einmal. Rufen Sie die API nicht mit einem leeren Wert auf. Ist ein Wert ungültig, stoppen Sie perform() und nutzen Sie IntentDialog, um den Satz zu schreiben, den die Person lesen kann. Das JSON oben ist der Eintrag, den Sie für diese Entscheidung behalten.

needs_value heißt: Sie müssen noch fragen. rejected heißt: dieser Kandidat darf nicht laufen. Keiner erreicht die API. Die Person sieht den dialog-Satz. Das Protokoll behält das ganze JSON, damit später klar ist, welches Feld den Aufruf gestoppt hat.

Abgrenzung zu den anderen Artikeln

Den Aufruf in JSONNote stoppen

1. 1
   Die richtige Operation wählen

   Öffnen Sie JSON Schema. Stellen Sie Betrieb auf Überprüfen Sie mit Schema. Kandidat ins erste Feld, das Schema oben ins zweite. intent darf nur PlaceOrderIntent sein. fulfillment nur pickup oder delivery. quantity muss eine Ganzzahl sein.

2. 2
   Drei ungültige Dokumente prüfen

   Setzen Sie fulfillment auf ship, quantity auf die Zeichenkette 1, oder löschen Sie itemId. Alle drei scheitern. quantity 0 besteht. Danach schreiben Sie trotzdem rejected und rufen die API nicht auf.

3. 3
   1 mit 0 vergleichen

   Öffnen Sie JSON Vergleiche Diff. parameters mit quantity 1 ins erste Feld, dasselbe Objekt mit quantity 0 ins zweite. Der Unterschied ist diese Zahl. 0 besteht das Schema weiter. Die API stoppt der Fehlereintrag, nicht diese Formprüfung.

Häufige Fragen

Prüfen Sie noch, wenn das System der App die Parameter schon übergeben hat?

Ja. Das System hat einen Aufruf übergeben, keine schon geprüfte API-Anfrage. Am Anfang von perform() lesen Sie dieses JSON. Besteht es nicht, machen Sie nicht weiter.

Darf die API laufen, wenn das Schema besteht?

Noch nicht. Dieses Schema prüft nur Typ, Enum und Pflichtfelder. quantity 0 besteht. Eine itemId als Zeichenkette besteht ebenfalls. Rufen Sie die API nur auf, wenn die Menge mindestens 1 ist und die Id sich auflöst.

Fehlt ein Parameter: Fehler zurückgeben oder noch einmal fragen?

Noch einmal fragen. Setzen Sie status auf needs_value und bitten Sie mit requestValue um den Wert. Rufen Sie die API nicht auf, bevor ein gültiger Wert da ist. Kommt der Wert und ist ungültig, schreiben Sie rejected.

Ist das derselbe Artikel wie der JSON-Pfad eines Auftrags?

Nein. Jener Artikel folgt einem Auftrag vom Satz zur API. Dieser bleibt in der App: Parametervertrag, Schema und das bei einem Fehler zurückgegebene JSON. Die API läuft nur, wenn weder rejected noch needs_value geschrieben wurde.

Ist der Fehlereintrag Apples Antwortformat?

Nein. Apple übergibt das Ergebnis mit requestValue und IntentDialog an System und Person. Dieses JSON ist Ihr eigenes Protokoll: status, reason, field, dialog. Behalten Sie es, um in JSONNote nachzusehen, warum die API nicht lief.

Fazit

Wird eine Drittanbieter-App aufgerufen, gibt es zuerst einen Parametervertrag und dann ein JSON, das scheitern darf. Der Fehlereintrag stoppt den Aufruf vor der API und behält einen dialog-Satz, den eine Person lesen kann.

Die Entscheidung: zuerst die Intent-Parameter deklarieren; das Schema stoppt falsche Typen, Enums und fehlende Pflichtfelder; needs_value, wenn ein Wert fehlt; rejected, wenn ein Wert ungültig ist; beides ohne API; Menge unter 1 oder fehlende Id stoppt auch bei gültiger Form.

Zurück zum Blog