Kanal-Identifikatoren festlegen
Ein Kanal-Identifikator ist der Identifikatorwert eines Zustellkanals und kann als Ziel dieses Kanals verwendet werden. Festlegen und Lösen erfolgen anhand von EUID und Kanal-ID.
Die vollständige Aufrufadresse besteht aus der Base URL des Rechenzentrums und dem unten genannten API-Pfad. Informationen zum Abrufen von Base URL, API Key und API Secret finden Sie in der RestAPI-Übersicht.
Authentifizierung des Aufrufs
Die EngageLab REST API verwendet HTTP Basic Authentication zur Authentifizierung. Fügen Sie dem HTTP-Header die Autorisierung hinzu:
Authorization: Basic ${base64_auth_string}
Der base64_auth_string wird nach folgendem Schema generiert: base64(api_key:api_secret).
- Der Header-Name ist „Authorization“, und der Wert ist das base64-codierte „Benutzername:Passwort“-Paar (Benutzername und Passwort durch Doppelpunkt getrennt).
- Für die MA API entspricht der Benutzername dem APIKey und das Passwort dem APISecret. Bitte konfigurieren Sie eine API-Datenquelle, um APIKey und APISecret zu erhalten.
Kanal-Identifikatoren festlegen
Aufrufadresse
POST /v1/user/channel
Beispiel für eine Anfrage
Anfrage-Header
> POST /v1/user/channel
> Content-Type: application/json
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
Anfrage-Body
{
"euid": 10362473,
"channel_id": 8801,
"ma_rid": "1a0018970d1c9f8f8e2",
"value": [
"channel_identifier_1",
"channel_identifier_2"
]
}
Anfrageparameter
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
euid |
Long | Ja | Eindeutige Benutzer-ID. Der Benutzer muss im aktuellen Projekt bereits vorhanden sein. |
channel_id |
Long | Ja | ID des Zustellkanals. Der Kanal muss im aktuellen Projekt bereits vorhanden sein. |
ma_rid |
String | Nein | MA Registration ID. Wenn sie übergeben wird, werden die in dieser Anfrage geschriebenen Kanal-Identifikatoren an diese MA RID gebunden und die Plattform wird gespeichert. Wechselt diese MA RID zu einer anderen EUID, werden die an sie gebundenen Kanal-Identifikatoren mit übertragen. Wird das Feld weggelassen, als leere Zeichenfolge oder nur aus Leerzeichen übergeben, entsteht bei diesem Schreiben keine Bindung; eine vorhandene Bindung der in dieser Anfrage geschriebenen Identifikatoren wird gelöscht. Lässt sich keine Plattform aus dem Wert lesen, schlägt das Festlegen fehl. |
value |
Array<String> | Ja | Liste der festzulegenden Kanal-Identifikatoren. Die Liste darf nicht leer sein, und kein Eintrag darf nur aus Leerzeichen bestehen. Werte werden unverändert gespeichert: Der Vergleich unterscheidet Groß- und Kleinschreibung, Leerzeichen am Anfang oder Ende werden nicht entfernt. Doppelte Werte in derselben Anfrage werden entfernt. |
Bei derselben Kombination aus euid und channel_id wird derselbe Identifikator anhand dieser Anfrage neu geschrieben: Der alte Datensatz wird gelöscht und ein neuer Datensatz geschrieben. Die Aktualisierungszeit wird auf die aktuelle Zeit gesetzt. Bereits gespeicherte Identifikatoren, die in dieser Liste fehlen, bleiben unverändert. Neue Werte werden angehängt.
Bei AppPush-/WebPush-Kanälen darf derselbe Kanal-Identifikator unter derselben channel_id nur einer EUID gehören. Nach dem erfolgreichen Schreiben auf die neue EUID entfernt das System den Wert von jeder anderen EUID, die ihn noch besitzt. Andere Kanaltypen verwenden diese eindeutige Umhängung nicht.
Rückgabeparameter
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
code |
Int | Ja | Gibt an, ob der API-Aufruf erfolgreich war. 0 bedeutet Erfolg. |
message |
String | Ja | Ergebnisbeschreibung des API-Aufrufs. |
Erfolgsbeispiel
{
"code": 0,
"message": "success"
}
Kanal-Identifikatoren lösen
Aufrufadresse
POST /v1/user/channel/unbind
Beispiel für eine Anfrage
Anfrage-Header
> POST /v1/user/channel/unbind
> Content-Type: application/json
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
Anfrage-Body
{
"euid": 10362473,
"channel_id": 8801,
"value": [
"channel_identifier_1",
"channel_identifier_2"
]
}
Anfrageparameter
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
euid |
Long | Ja | Eindeutige Benutzer-ID. |
channel_id |
Long | Ja | ID des Zustellkanals. |
value |
Array<String> | Ja | Liste der zu lösenden Kanal-Identifikatoren. Jeder Wert muss exakt einem gespeicherten Identifikator entsprechen. Der Vergleich unterscheidet Groß- und Kleinschreibung, Leerzeichen am Anfang oder Ende werden nicht entfernt. |
Das Lösen vergleicht Kanal-Identifikatoren, nicht ma_rid. Die Löse-Anfrage hat kein Feld ma_rid. Die API entfernt Datensätze, die exakt mit euid + channel_id + value übereinstimmen. Existiert der Benutzer nicht oder hat er keinen exakt passenden Identifikator, werden keine Daten geändert und die API gibt trotzdem Erfolg zurück. Das Lösen prüft nicht, ob channel_id zum aktuellen Projekt gehört.
Rückgabeparameter
| Feld | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
code |
Int | Ja | Gibt an, ob der API-Aufruf erfolgreich war. 0 bedeutet Erfolg. |
message |
String | Ja | Ergebnisbeschreibung des API-Aufrufs. |
Erfolgsbeispiel
{
"code": 0,
"message": "success"
}
Fehlercodes
Schlägt die fachliche Prüfung fehl, gibt die Setz-API die folgenden Fehlercodes mit HTTP-Status 400 zurück. Das Feld message im Antworttext ist die englische Erklärung, nicht die Beschreibung in der folgenden Tabelle. Die Löse-API gibt 55004 nur zurück, wenn ein Pflichtfeld ungültig ist oder der Anfragetext nicht gelesen werden kann. Existiert der Benutzer oder der Identifikator nicht, gibt das Lösen trotzdem Erfolg zurück.
| Fehlercode | Beschreibung | Detail |
|---|---|---|
| 55004 | Ungültiger Geschäftsparameter | Existiert channel_id beim Festlegen im aktuellen Projekt nicht, lautet message channel_id does not exist in current project: {channel_id}. Lässt sich beim Festlegen aus ma_rid keine Plattform lesen, lautet message ma_rid is invalid. Beim Festlegen und Lösen führen ein fehlendes Pflichtfeld, ein leeres value, ein Eintrag nur aus Leerzeichen oder ein nicht lesbarer Anfragetext (dann lautet message Invalid request payload format) ebenfalls zu diesem Code. |
| 55108 | Ungültige EUID | Wird nur von der Setz-API zurückgegeben. Die EUID existiert im aktuellen Projekt nicht. message lautet EUID does not exist: {euid}. |
Fehlerbeispiele
channel_id existiert nicht:
{
"code": 55004,
"message": "channel_id does not exist in current project: 8801"
}
ma_rid kann nicht gelesen werden:
{
"code": 55004,
"message": "ma_rid is invalid"
}
Die EUID existiert nicht:
{
"code": 55108,
"message": "EUID does not exist: 10362473"
}
