Zum Hauptinhalt springen

Typisierte Ressourcenvarianten

Manche Ressourcen besitzen eine feste Menge von Varianten mit unterschiedlichen Feldern. Ihre OpenAPI-Schemas verwenden oneOf mit einem verpflichtenden Diskriminator wie kind, type oder auth_method. Prüfen Sie dieses Feld vor dem Zugriff auf variantenspezifische Eigenschaften. Jeder Zweig beschreibt das vollständige Objekt.

Geräte​

Beim Erstellen über die öffentliche API ist kind erforderlich. Ohne dieses Feld wird kein Standardtyp ausgewählt.

kindErforderliche VariantenfelderVerhalten bei der Einrichtung
TOURFOLD_APPplatform: IOS oder ANDROIDdevice_identity_id kann bei der Registrierung zugeordnet werden.
THIRD_PARTY_OSMANDKeine weiteren Pflichtfelder neben kindDie erste eingehende Meldung kann device_identity_id zuordnen. Die Plattform ist standardmäßig UNKNOWN.
TRACKING_DEVICEdevice_identity_id, connection_profileHardware-Ortung muss aktiviert sein und das gewählte Profil unterstützt werden.
{ "kind": "TOURFOLD_APP", "platform": "IOS", "description": "Telefon für Lieferungen" }

device_model, phone_number und description sind optional. Nur Ortungshardware besitzt connection_profile. Antworten verwenden dieselben Varianten: Identität und Profil sind für Ortungshardware erforderlich; bei App- und OsmAnd-Geräten kann die Identität während der Einrichtung noch fehlen.

Bei PATCH muss kind nicht erneut gesendet werden. Die Validierung richtet sich nach dem gespeicherten Typ: Der Typ ist unveränderlich, Identität und Profil von Ortungshardware können nicht gelöscht werden, und die App-Plattform muss IOS oder ANDROID bleiben. Ausgelassene Felder bleiben unverändert. Ein ausdrückliches null löscht ein optionales Feld, soweit die Variante dies erlaubt. Eine vorhandene Identität kann nicht direkt durch eine andere ersetzt werden.

SMS-Gateways​

type: "TWILIO" erfordert twilio_config; type: "CUSTOM_HTTP" erfordert custom_config. Felder des jeweils anderen Anbieters werden abgelehnt. PATCH darf type auslassen. Eine übergebene Konfiguration ersetzt die bisherige Konfiguration und muss zum gespeicherten Anbieter passen.

Benutzerdefinierte HTTP-Einstellungen erfordern ein ausdrückliches auth_method, auch NONE für Endpunkte ohne Authentifizierung:

auth_methodErforderlicher Authentifizierungsblock
NONEKeiner; Authentifizierungsblöcke fehlen.
OAUTHoauth mit Token-Endpunkt und Client-Zugangsdaten.
BASICbasic mit Benutzername und Passwort.
API_KEY_HEADERapi_key mit Headername und Headerwert.

Jeder Parameter besitzt key, place und type. place wählt QUERY, HEADER, PATH, JSON_BODY oder FORM_BODY. RECIPIENT übernimmt den Empfänger und MESSAGE_VALUE den Text der Nachricht; beide akzeptieren kein static_value. SENDER_NUMBER, AUTH und EXTRA benötigen für static_value einen nicht leeren String. Es gibt keinen Ersatzwert aus zusätzlichen Laufzeitparametern. Fehlende feste Werte werden vor dem Versand abgelehnt.

{
"name": "Benutzerdefiniertes SMS-Gateway",
"type": "CUSTOM_HTTP",
"custom_config": {
"url": "https://sms.example.com/send",
"http_method": "POST",
"auth_method": "NONE",
"parameters": [
{ "key": "to", "place": "JSON_BODY", "type": "RECIPIENT" },
{ "key": "text", "place": "JSON_BODY", "type": "MESSAGE_VALUE" },
{ "key": "sender", "place": "JSON_BODY", "type": "SENDER_NUMBER", "static_value": "Tourfold" }
]
}
}

Fehlende Pflichtfelder und Felder einer anderen Variante führen zu einem feldbezogenen 422, auch mit verschachtelten Zeigern wie #/custom_config/parameters/0/static_value.

Weitere Ressourcenvarianten​

  • Favoriten wählen über kind entweder das verpflichtende folder- oder document-Objekt.
  • Webhook-Momentaufnahmen von Aufgabeninteraktionen enthalten options für single_choice oder max_length für free_text. Die Antwortmetadaten bleiben eingeschränkt: Freitextantworten und Kommentare werden nicht mitgeliefert.
  • Workflow-Titeltokens verwenden literal, record_field, trigger_field oder output_field. Literale besitzen text; Feldtokens enthalten die Eigenschaften eines Feldverweises. Entwürfe dürfen unvollständig sein. Beim Veröffentlichen gelten die vollständigen Validierungsregeln.

Ein Diskriminator ersetzt weder gewöhnliche Aufzählungen noch beliebige JSON-Werte. Bei löschbaren PATCH-Feldern bleiben Auslassen und Löschen getrennt. Felder mit JSON-Werten behalten ein bedeutungstragendes ausdrückliches null. Siehe Schreibsemantik und Veröffentlichung von Workflows.