Blog • AI / App Intents

Wie fließt das JSON einer App Action, nachdem iOS 27 mehr Siri-Aktionen öffnet? Vom gesprochenen Auftrag zum API-Aufruf

JSONNote Team

| Veröffentlicht am 2026-09-28 | Aktualisiert am 2026-09-28 Etwa 12 Minuten

Ein Siri-Auftrag läuft, weil er zuerst App-Intent-Parameter wird und AppIntent in perform() entscheidet, ob er auf dem Gerät bleibt oder Ihre API ruft. Das System schickt die rohe Äußerung nicht an Ihren Server.

Ob Siri ein Agent ist, steht im vorherigen Artikel. Dieser folgt einem Auftrag: wie ein Satz den Intent wählt, wie Parameter zu JSON werden und warum die API erst nach der Prüfung läuft.

Ein Satz trifft einen App Shortcut. Die Äußerung wird nicht als freier Text ausgeführt
Drei Parameterarten: eingebaute Typen, ein AppEnum zur Compile-Zeit, eine AppEntity mit Abfrage
Eine Entität liefert eine stabile Id. Die Abfrage lädt Ihre Daten darüber
Das Parameter-JSON gehört Ihnen. Es ist nicht Apples Übertragungsformat
Ist resolved false oder das Schema scheitert, rufen Sie die API nicht. Der Dialog geht zurück an Siri

Zuerst festhalten: Sprache ist nicht der Request-Body. Die gefüllten Intent-Parameter sind es. Danach: Satz, Parametertyp, Entitäts-Id, Ihr JSON, dann die API.

Fünf Schritte eines Auftrags

Der offizielle Einstieg ist App Intents. Siehe Einstieg in App Intents. Siri, Kurzbefehle und ein Button in der App teilen einen Intent. Sie unterscheiden sich darin, wer die Parameter füllt.

1
Satz treffen
Gesprochene Sätze registrieren Sie auf AppShortcutsProvider. Das System wählt damit einen Intent. Es gibt den Rohsatz nicht einem Modell zum Improvisieren.
2
Parameter füllen
Jedes @Parameter am Intent sagt dem System, welchen Wert es braucht und ob er Pflicht ist. Fehlt er, wird nachgefragt. Es wird nicht geraten und gesendet.
3
Entität auflösen
Nutzerdaten löst EntityQuery über id auf. Der Parameter hält die Entität, nicht einen beschreibenden Absatz.
4
Ausführen
In perform() lesen Sie schon aufgelöste Werte. Was das Gerät allein schafft, endet dort.
5
Siri antworten
Das Ergebnis kommt über IntentResult oder einen Dialog zurück. Ein Fehler braucht einen Satz, den man hören kann. Nicht nur ein Serverprotokoll.

Drei Arten von Parametern

Die Typen stehen in Parameter zu einem App Intent hinzufügen. Der falsche Typ macht das spätere JSON instabil.

Typ	Dafür	Im JSON
String, Zahl, Datum	Einfache Eingabe wie Menge oder Notiz	Unverändert in parameters
`AppEnum`	Eine zur Compile-Zeit feste Menge, etwa Abholung oder Lieferung	Den Enum-Wert speichern. Nicht den Anzeigetext als Schlüssel
`AppEntity`	Nutzerdaten, die sich ändern, etwa ein Produkt	Nur die aufgelöste Id speichern

Eine feste Menge ist ein AppEnum. Eine Liste, die Personen ändern, ist eine AppEntity plus Abfrage. Modellieren Sie eine wechselnde Liste als Enum, passen Sätze nicht mehr, sobald eine Option veraltet.

Eine Entität behält nur die Id

Das System braucht eine Entität, die es anzeigen und abfragen kann. Ihre Datenbank bleibt die Quelle. Die Entität braucht mindestens eine stabile Id und einen lesbaren Namen.

Die Entitätsfelder, die Sie nach der Auflösung notieren können. Die Id ist später der Schlüssel der API.

{
  "entity": "OrderItem",
  "id": "sku_42",
  "display": "Oat milk"
}

Implementieren Sie entities(for identifiers:) und laden Sie das Objekt über die Id. Fehlt es, erfinden Sie keine Id und machen nicht weiter.

Das Parameter-JSON, das Ihnen gehört

Das Dokument unten ist der Vertrag, den Sie in perform() speichern, bevor Sie die API entscheiden. Es ist nicht Apples Request-Format, und das System liest die Datei nicht für Sie.

Ein aufgelöster Bestellauftrag. resolved ist nur true, wenn die Entitätsabfrage gelingt.

{
  "intent": "StartOrder",
  "source": "siri",
  "parameters": {
    "item_id": "sku_42",
    "quantity": 1
  },
  "resolved": true
}

intent nutzt den Intent-Typnamen, damit er zur Aktion in Kurzbefehlen passt.
item_id ist die Entitäts-Id, nicht der gesprochene Satz. Der Satz kann sich ändern. Die Id soll es nicht.
Ist resolved false, ist die Auflösung offen oder die Person hat die Nachfrage abgebrochen. Die API nicht rufen.
Keine rohe Äußerung, keine Ortsspur und kein Token in dieses JSON.

Wann die API aufgerufen wird

1
Auf dem Gerät fertig
Eine Aktion, die nur lokalen Zustand ändert, endet in perform(). Sie braucht kein Netz.
2
Zuerst prüfen
Brauchen Sie einen Server, prüfen Sie das JSON zuerst mit einem Schema. Fehlt item_id oder ist quantity unter 1, bleibt es auf dem Gerät.
3
Dann ins Netz
parameters geht erst an Ihre API, wenn die Prüfung besteht und resolved true ist. Der Server sucht seinen eigenen Datensatz über die Id. Dem Anzeigenamen vertraut er nicht.
4
Den Fehler verständlich sagen
Lehnt die API ab oder läuft die Zeit ab, sagen Sie über den Intent-Dialog, dass es nicht fertig wurde. Siri soll nicht Erfolg melden.

Wie eine Drittanbieter-App den Intent deklariert und einen Fehler zurückgibt, ist der nächste Artikel. Dieser endet beim Datenweg.

Abgrenzung zu älteren Artikeln

	Ist Siri ein Agent?	Dieser Artikel
Frage	Ob das System selbst plant und Werkzeuge aufruft	Welches JSON ein Auftrag auf dem Weg zur API durchläuft
Hier nicht suchen	Noch eine Produktankündigung	Die rohe Äußerung als speicherbaren Request-Body zu behandeln

Die Produkterzählung zu Hardware und Systemfunktionen steht in warum iPhone 18 mehr als Hardware ist. Dort werden keine Parameterfelder zerlegt.

Dieses JSON in JSONNote prüfen

1
Formatieren
Öffnen Sie den Parametereintrag in JSON formatieren und prüfen Sie, dass kein nachgestelltes Komma da ist.
2
Fehlende Felder mit einem Schema stoppen
Fügen Sie das Schema unten in JSON Schema ein. Fehlen intent oder item_id oder ist quantity keine positive Ganzzahl, darf es nicht an die API.
3
Dann ein Beispiel prüfen
Fügen Sie ein echtes Beispiel in JSON prüfen ein. Achten Sie darauf, ob item_id ein leerer String ist.

JSON Schema für den Parametereintrag. source erlaubt nur siri, shortcut und app.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "required": ["intent", "source", "parameters", "resolved"],
  "properties": {
    "intent": { "type": "string", "minLength": 1 },
    "source": { "enum": ["siri", "shortcut", "app"] },
    "resolved": { "type": "boolean" },
    "parameters": {
      "type": "object",
      "required": ["item_id", "quantity"],
      "properties": {
        "item_id": { "type": "string", "minLength": 1 },
        "quantity": { "type": "integer", "minimum": 1 }
      }
    }
  }
}

Häufige Fragen

Schickt das System die ganze Äußerung an meinen Server?

Nicht auf diesem Weg. Der Server soll das Parameter-JSON bekommen, das Sie in perform() bauen und prüfen. Die Sprache bleibt in der Erkennung auf dem Gerät.

Warum steht der Produktname nicht direkt in den Parametern?

Namen ändern sich und kollidieren. Eine AppEntity nutzt eine stabile Id, die Abfrage lädt das Objekt darüber. Die API soll nur die Id akzeptieren.

Darf ich die API rufen, sobald das Schema passt?

Prüfen Sie auch resolved. Eine gültige Form mit unaufgelöster Entität heißt: Die Person hat das Objekt noch nicht gewählt. Ein API-Aufruf macht aus einer Nachfrage eine falsche Bestellung.

Wie trennt man lokale Arbeit von einem Netzaufruf?

Was nur lokale Daten ändert, endet in perform(). Was Ihr Backend braucht, schreibt das Parameter-JSON, prüft es und ruft dann. Beide Wege geben das Ergebnis über IntentResult zurück.

Ist ein Kurzbefehl mit von Hand gefüllten Parametern derselbe Weg?

Ja, derselbe AppIntent. Der Unterschied ist, wer die Parameter füllt: Siri über den Satz, Kurzbefehle über die Person oder die vorige Aktion. Entität, JSON und das API-Tor bleiben gleich.

Fazit

Der Datenweg eines Auftrags: Ein Satz wählt den Intent, Parameter werden nach Typ gefüllt, die Entität wird zur Id, Sie schreiben JSON, die API läuft erst nach der Prüfung, und ein Dialog gibt das Ergebnis an Siri zurück.

Direktes Fazit: die rohe Äußerung nicht hochladen. Die API nicht rufen, bevor die Id aufgelöst ist. Einen Fehler der Person sagen, nicht nur ins Serverprotokoll schreiben.

Als Nächstes: dieses Parameter-JSON mit einem Schema sperren, bevor Sie es an perform() hängen.

Mit JSON Schema prüfen JSON formatieren JSON prüfen

Zurück zum Blog