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.
kind | Erforderliche Variantenfelder | Verhalten bei der Einrichtung |
|---|---|---|
TOURFOLD_APP | platform: IOS oder ANDROID | device_identity_id kann bei der Registrierung zugeordnet werden. |
THIRD_PARTY_OSMAND | Keine weiteren Pflichtfelder neben kind | Die erste eingehende Meldung kann device_identity_id zuordnen. Die Plattform ist standardmäßig UNKNOWN. |
TRACKING_DEVICE | device_identity_id, connection_profile | Hardware-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_method | Erforderlicher Authentifizierungsblock |
|---|---|
NONE | Keiner; Authentifizierungsblöcke fehlen. |
OAUTH | oauth mit Token-Endpunkt und Client-Zugangsdaten. |
BASIC | basic mit Benutzername und Passwort. |
API_KEY_HEADER | api_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
kindentweder das verpflichtendefolder- oderdocument-Objekt. - Webhook-Momentaufnahmen von Aufgabeninteraktionen enthalten
optionsfürsingle_choiceodermax_lengthfürfree_text. Die Antwortmetadaten bleiben eingeschränkt: Freitextantworten und Kommentare werden nicht mitgeliefert. - Workflow-Titeltokens verwenden
literal,record_field,trigger_fieldoderoutput_field. Literale besitzentext; 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.