Dokumentation Campaign Dokumentation om Campaign Standard

Externt API external-api

Last update: Fri Jul 19 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Ämnen:

Skapat för:

Erfaren
Utvecklare

Beskrivning description

Aktiviteten External API hämtar data till arbetsflödet från ett externt system via ett HTTP API-anrop.

De externa systemslutpunkterna kan vara offentliga API-slutpunkter, kundhanteringssystem eller serverlösa programinstanser (t.ex. Adobe I/O Runtime) för att nämna några kategorier.

NOTE

Av säkerhetsskäl stöds inte JSSP:er i Campaign Standard. Om du behöver köra kod kan du anropa en Adobe I/O Runtime-instans via aktiviteten External API.

De viktigaste egenskaperna för denna aktivitet är:

Möjlighet att skicka data i ett JSON-format till en REST API-slutpunkt från tredje part
Möjlighet att få ett JSON-svar tillbaka, mappa det till utdatatabeller och skicka det vidare till andra arbetsflödesaktiviteter.
Felhantering med en utgående specifik övergång

Bakåtkompatibilitetsmeddelanden from-beta-to-ga

I Campaign Standard 20.4 har http-svarets datastorleksgräns och timeout-skydd sänkts för att anpassas till bästa praxis - se Begränsningar och skyddsutkast. Dessa skyddsändringar träder ej i kraft för befintliga externa API-aktiviteter. Vi rekommenderar därför att du ersätter befintliga externa API-aktiviteter med nya versioner i alla arbetsflöden.

När du ersätter Extern API-aktiviteter lägger du till den nya Extern API-aktiviteten i arbetsflödet, kopierar manuellt över konfigurationsinformationen och tar sedan bort den gamla aktiviteten.

NOTE

Du kan inte kopiera över aktivitetsspecifika rubrikvärden eftersom de är maskerade i aktiviteten.

Begränsningar och skyddsräcken guardrails

Följande skydd gäller för den här aktiviteten:

5 MB gräns för datastorlek på http-svar (Obs! Detta är en ändring från gränsen på 50 MB i föregående version)
Tidsgränsen för begäran är 1 minut (Obs! Detta är en ändring från tidsgränsen på 10 minuter i föregående version)
HTTP-omdirigeringar tillåts inte
URL:er som inte är HTTPS nekas
Begäranderubriken "Acceptera: application/json" och svarsrubriken "Innehållstyp: application/json" är tillåtna

Särskilda skydd har införts:

Maximalt JSON-djup: Begränsa det maximala djupet för en anpassad kapslad JSON som kan bearbetas till 10 nivåer.
Maximal längd på JSON-nyckel: Begränsa maxlängden för den interna nyckel som genereras till 255. Den här nyckeln är kopplad till kolumn-ID:t.
Maximalt antal tillåtna JSON-dubblettnycklar: Begränsa det maximala antalet dubbla JSON-egenskapsnamn, som används som kolumn-ID, till 150.

CAUTION

Den externa API-aktiviteten är avsedd att hämta kampanjomfattande data (senaste erbjudanden och senaste poängen o.s.v.) och inte att hämta specifik information för varje profil eftersom det kan leda till att stora mängder data överförs. Om användningsfallet kräver detta ska aktiviteten Överför fil användas.

Konfiguration configuration

Dra och släpp en External API-aktivitet i arbetsflödet och öppna aktiviteten för att starta konfigurationen.

Inkommande mappning

Inkommande mappning är en tillfällig tabell som genereras av en tidigare inkommande aktivitet som visas och skickas som JSON i användargränssnittet.
Utifrån den här tillfälliga tabellen kan användaren ändra inkommande data.

I listrutan Inkommande resurs kan du välja den frågeaktivitet som ska skapa det tillfälliga registret.

Kryssrutan Lägg till antalparameter lägger du till ett räkningsvärde för varje rad som kommer från den tillfälliga tabellen. Observera att den här kryssrutan endast är tillgänglig om den inkommande aktiviteten genererar en tillfällig tabell.

I avsnittet Inkommande kolumner kan användaren lägga till fält från den inkommande övergångstabellen. De markerade kolumnerna är nycklarna i dataobjektet. Dataobjektet i JSON blir en matrislista som innehåller data för markerade kolumner från varje rad i tabellen för inkommande övergångar.

I textrutan Anpassa parametrar kan du lägga till en giltig JSON med ytterligare data som behövs för det externa API:t. Dessa ytterligare data läggs till i params-objektet i den genererade JSON:n.

Utgående mappning

På den här fliken kan du definiera exempelstrukturen för JSON som returneras av API-anropet.

JSON-tolkaren är utformad för att rymma JSON-standardstrukturmönstertyper, med några undantag. Ett exempel på ett standardmönster är:{“data”:[{“key”:“value”}, {“key”:“value”},...]}

JSON-exempeldefinitionen måste ha följande egenskaper:

Matriselement måste innehålla egenskaper på första nivån (djupare nivåer stöds inte).
Egenskapsnamn blir till kolumnnamn för utdatabladet i den tillfälliga utdatatabellen.
JSON-element som ska hämtas måste vara på 10 eller färre kapslingsnivåer inom JSON-svaret.
Kolumnnamnsdefinitionen baseras på det första elementet i matrisen "data".
Kolumndefinition (lägg till/ta bort) och egenskapens typvärde kan redigeras på fliken Kolumndefinition.

Beteende Förenkla kryssrutan:

Förenkla kryssrutan (standard: omarkerad) tillhandahålls för att ange om JSON ska förenklas till en nyckel/värdekarta eller inte.

När kryssrutan är inaktiverad (avmarkerad) tolkas JSON-exempelfilen så att den söker efter ett matrisobjekt. Användaren måste ange en trimmad version av JSON-formatet för API-svarsexemplet så att Adobe Campaign kan avgöra exakt vilken matris som användaren är intresserad av att använda. Vid redigering av arbetsflödet bestäms och registreras sökvägen till det kapslade matrisobjektet så att den kan användas vid körning för att komma åt det matrisobjektet från JSON-svarstexten som tas emot från API-anropet.
När kryssrutan är aktiverad (markerad) förenklas JSON-exempelfilen och alla egenskaper som anges i det angivna exemplet JSON används för att skapa kolumner i den tillfälliga utdatatabellen och visas på fliken Kolumndefinitioner. Observera att om det finns ett matrisobjekt i JSON-exempelfilen, kommer även alla element i dessa matrisobjekt att förenklas.

Om tolkningen valideras visas ett meddelande som uppmanar dig att anpassa datamappningen på fliken Kolumndefinition. I andra fall visas ett felmeddelande.

Körning

Med den här fliken kan du definiera anslutningens slutpunkt. I fältet URL kan du definiera den HTTPS-slutpunkt som Campaign Standarden ska kommunicera med.

Om slutpunkten kräver det finns det två typer av autentiseringsmetoder:

Grundläggande autentisering: ange användarnamn/lösenord i avsnittet Request Header(s).
OAuth-autentisering: Genom att klicka på Use connection parameters defined in an external account i ett externt konto kan du välja ett externt konto där OAuth-autentiseringen definieras. Se avsnittet Externa konton för mer information.

Egenskaper

På den här fliken kan du styra allmänna egenskaper för den externa API-aktiviteten, som t.ex. etiketten som visas i gränssnittet. Det interna ID:t kan inte anpassas.

Kolumndefinition

NOTE

Den här fliken visas när svarsdataformatet har slutförts och validerats på fliken Utgående mappning.

På fliken Kolumndefinition kan du ange datastrukturen exakt för varje kolumn för att importera data som inte innehåller några fel och få dem att matcha de typer som redan finns i Adobe Campaign-databasen för framtida åtgärder.

Du kan till exempel ändra etiketten för en kolumn och välja dess typ (sträng, heltal, datum, etc.) eller specificera felbearbetning.

Mer information finns i avsnittet Läs in fil.

Övergång

På den här fliken kan du aktivera den utgående övergången och dess etikett. Den här specifika övergången är användbar vid timeout eller om nyttolasten överskrider datastorleksgränsen.

Körningsalternativ

Den här fliken är tillgänglig i de flesta arbetsflödesaktiviteter. Mer information finns i avsnittet Aktivitetsegenskaper.

Testning

Om du vill testa den externa API-funktionen med en enkel testslutpunkt kan du använda Postman Echo: https://docs.postman-echo.com.

Felsökning

Två typer av loggmeddelanden har lagts till i den nya arbetsflödesaktiviteten: information och fel. De kan hjälpa dig att felsöka potentiella problem.

Information

Dessa loggmeddelanden används för att logga information om användbara kontrollpunkter när arbetsflödesaktiviteten körs.

Meddelandeformat

Exempel

Invoking API URL '%s'.

Anropar API-URL:en "https://example.com/api/v1/web-coupon?count=2".

Retrying API URL '%s' due to %s in %d ms, attempt %d.

Försöker igen med API-URL 'https://example.com/api/v1/web-coupon?count=0' på grund av HTTP - 401 på 2364 ms, försök 2.

Transferring content from '%s' (%s / %s).

Överför innehåll från "https://example.com/api/v1/web-coupon?count=2" (1234/1234).

Using cached access token for provider ID '%s'.

Använder cachelagrad åtkomsttoken för leverantörs-ID 'EXT25'. Obs! EXT25 är ID-numret (eller namnet) på det externa kontot.

Fetched access token from server for provider ID '%s'.

Åtkomsttoken för leverantörs-ID 'EXT25’ har hämtats från servern. Obs! EXT25 är ID-numret (eller namnet) på det externa kontot.

Refreshing OAuth access token due to error (HTTP: '%d').

Uppdatera OAuth-åtkomsttoken på grund av fel (HTTP: '401').

Error refreshing OAuth access token (error: '%d').

Fel vid uppdatering av OAuth-åtkomsttoken (fel: '404').

Failed to fetch the OAuth access token using the specified external account on attempt %d, retrying in %d ms.

Det gick inte att hämta OAuth-åtkomsttoken med det angivna externa kontot på försök 1. Ett nytt försök görs om 1387 ms.

Fel

Dessa loggmeddelanden används för att logga information om oväntade feltillstånd som kan göra att arbetsflödesaktiviteten misslyckas.

Kod – Meddelandeformat

Exempel

WKF-560250 - API request body exceeded limit (limit: '%d').

API-begärans brödtext överskreds (gräns: "5242880").

WKF-560239 - API response exceeded limit (limit: '%d').

API-svaret överskrider gränsen (gräns: "5242880").

WKF-560245 - API URL could not be parsed (error: '%d').

API-URL kunde inte tolkas (fel: "-2010").

Obs! Det här felet loggas när API-URL:en inte stöder verifieringsregler.

WKF-560244 - API URL host must not be 'localhost', or IP address literal (URL host: '%s').

API-URL-värden får inte vara localhost eller bokstavlig IP-adress (URL-värd: "localhost").

API-URL-värden får inte vara localhost eller bokstavlig IP-adress (URL-värd: "192.168.0.5").

API-URL-värden får inte vara localhost eller bokstavlig IP-adress (URL-värd: [2001]).

WKF-560238 - API URL must be a secure URL (https) (requested URL: '%s').

API-URL:en måste vara en säker URL (https) (begärd URL: "https://example.com/api/v1/web-coupon?count=2").

WKF-560249 – Det gick inte att skapa JSON för begärandetext. Error when adding '%s'.

Det gick inte att skapa JSON för begärandetext. Ett fel uppstod när "params" skulle läggas till.

Det gick inte att skapa JSON för begärandetext. Ett fel uppstod när "data" skulle läggas till.

WKF-560246 - HTTP header key is bad (header key: '%s').

HTTP header key is bad (header key: '%s').

Obs! Det här felet loggas när den anpassade rubriknyckeln inte kan valideras enligt RFC

WKF-560248 - HTTP header key is not allowed (header key: '%s').

HTTP-rubriknyckeln tillåts inte (rubriknyckeln: "Godkänn").

WKF-560247 - Ett HTTP-rubrikvärde är felaktigt (rubrikvärde: '%s').

HTTP header value is bad (header value: '%s').

Obs! Det här felet loggas när det anpassade rubrikvärdet inte kan valideras enligt RFC

WKF-560240 - JSON payload has bad property '%s'.

JSON-nyttolasten har den felaktiga egenskapen "blah".

WKF-560241 - Malformed JSON or unacceptable format.

Felformaterad JSON eller ogiltigt format.

Obs! Det här meddelandet gäller endast för tolkning av svarstexten från det externa API:t, och loggas när du försöker validera om svarstexten uppfyller det JSON-format som krävs för den här aktiviteten.

WKF-560246 - Activity failed (reason: '%s').

När aktiviteten misslyckas på grund av HTTP 401-felsvar – Aktiviteten misslyckades (orsak: HTTP – 401)

När aktiviteten misslyckas på grund av ett misslyckat internt anrop – Aktiviteten misslyckades (orsak: "iRc – -Nn").

När aktiviteten misslyckas på grund av en ogiltig rubrik av innehållstyp. – Aktiviteten misslyckades (orsak: "Innehållstyp – application/html").

WKF-560278 - "Error initializing OAuth helper (error: '%d')" .

Detta fel indikerar att aktiviteten inte kunde initiera den interna hjälpfunktionen för OAuth2.0 på grund av ett fel i att använda attributen som har konfigurerats på det externa kontot för att initiera hjälpfunktionen.

WKF-560279 - "HTTP header key is not allowed (header key: '%s')."

Det här varningsmeddelandet (inte felmeddelandet) anger att det externa OAuth 2.0-kontot har konfigurerats för att lägga till en referens som HTTP-rubrik men rubriknyckeln som används tillåts inte eftersom det är en reserverad rubriknyckel.

WKF-560280 - External account of '%s' ID cannot be found.

Det går inte att hitta det externa kontot med ID-numret 'EXT25'. Obs! Det här felet indikerar att aktiviteten har konfigurerats för att använda ett externt konto som inte längre kan hittas. Detta inträffar troligast när kontot har tagits bort från databasen och inträffar därför i vanliga fall inte under normala driftförhållanden.

WKF-560281 - External account of '%s' ID is disabled.

Externt konto med ID-numret 'EXT25' är inaktiverat. Obs! Det här felet indikerar att aktiviteten har konfigurerats för att använda ett externt konto men att kontot har inaktiverats (eller markerats som inaktivt).

WKF-560282 - Protocol not supported.

Det här felet anger att det externa konto som är associerat med aktiviteten inte är ett externt OAuth2.0-konto. Därför är det osannolikt att det här felet inträffar om det inte finns några skador eller manuella ändringar i aktivitetskonfigurationen.

WKF-560283 - Failed to fetch the OAuth access token.

Den vanligaste orsaken till det här felet är en felkonfigurering av det externa kontot (såsom att använda det externa kontot utan att testa att anslutningen fungerar). Det kan vara möjligt att webbadressen/autentiseringsuppgifterna för det externa kontot ändrats.

CRL-290199 - Cannot reach page at: %s.

Det här felmeddelandet visas på skärmen med det externa kontots användargränssnitt när det konfigureras för OAuth. Detta innebär att webbadressen för den externa auktoriseringsservern antingen är felaktig/ändrad eller att svaret från servern är ”Sidan hittades inte”.

CRL-290200 - Incomplete/Incorrect credentials.

Det här felmeddelandet visas på skärmen med det externa kontots användargränssnitt när det konfigureras för OAuth. Detta innebär att autentiseringsuppgifterna antingen är felaktiga eller att andra nödvändiga autentiseringsuppgifter saknas för att ansluta till autentiseringsservern.

recommendation-more-help

3ef63344-7f3d-48f9-85ed-02bf569c4fff