Externe API external-api
Beschrijving description
De activiteit External API brengt data vanaf een extern systeem in de workflow via een HTTP API-aanroep.
De eindpunten van het externe systeem kunnen openbare API-eindpunten, klantenbeheersystemen of serverloze applicatie-instanties (bijvoorbeeld Adobe I/O Runtime) zijn, om maar een paar categorieën te noemen.
De belangrijkste kenmerken van deze activiteit zijn:
- Mogelijkheid om data in een JSON-indeling door te geven aan een REST API-eindpunt van derden
- Mogelijkheid om een JSON-antwoord terug te krijgen, het toe te wijzen aan uitvoertabellen en stroomafwaarts door te geven aan andere workflowactiviteiten.
- Het beheer van mislukkingen met een specifieke uitgaande overgang
Berichten over achterwaartse compatibiliteit from-beta-to-ga
Met de release van Campaign Standard 20.4 zijn de beperking voor de grootte van de http-responsgegevens en de instructies voor de time-out van de reactie verlaagd om deze af te stemmen op de best practices - zie Beperkingen en geleiders. Deze beveiligingswijzigingen gelden niet voor bestaande Externe API-activiteiten; daarom wordt u aangeraden bestaande Externe API-activiteiten in alle workflows te vervangen door nieuwe versies.
Wanneer u activiteiten voor Externe API vervangt, voegt u de nieuwe activiteit Externe API toe aan de workflow, kopieert u handmatig de configuratiedetails en verwijdert u vervolgens de oude activiteit.
Beperkingen en geleiders guardrails
Op deze activiteit zijn de volgende beveiligingen van toepassing:
- Groottelimiet van 5 MB voor http-responsdata (opmerking: dit is een wijziging ten opzichte van de limiet van 50 MB in de vorige release)
- De time-out van de aanvraag is 1 minuut (opmerking: dit is een wijziging ten opzichte van de time-out van 10 minuten in de vorige release)
- HTTP-omleidingen zijn niet toegestaan
- Niet-HTTPS-URL's worden geweigerd
- Aanvraagheader ‘Accept: application/json’ en antwoordheader ‘Content-Type: application/json’ zijn toegestaan
Er zijn specifieke beveiligingen aangebracht:
- JSON Max Depth: Beperk de maximumdiepte van een aangepaste geneste JSON die kan worden verwerkt tot 10 niveaus.
- JSON Max Key Length: Beperk de maximumlengte van de gegenereerde interne sleutel tot 255. Deze sleutel is gekoppeld aan de kolom-id.
- JSON Max Duplicate Keys Allowed: Beperk het maximumaantal dubbele JSON-eigenschapsnamen, die als kolom-id worden gebruikt, tot 150.
Configuratie configuration
Sleep een activiteit External API en zet deze neer in uw workflow en open de activiteit om de configuratie te beginnen.
Inbound Mapping
Inbound mapping is een tijdelijke tabel die door een vorige binnenkomende activiteit wordt gegenereerd en die als JSON in de gebruikersinterface wordt weergegeven en verzonden.
Op basis van deze tijdelijke tabel kan de gebruiker wijzigingen in binnenkomende data aanbrengen.
Met de vervolgkeuzelijst Inbound resource kunt u de activiteit Query selecteren waardoor de tijdelijke tabel zal worden gemaakt.
Met het selectievakje Add count parameter wordt een telwaarde toegevoegd voor elke rij die uit de tijdelijke tabel komt. Merk op dat dit selectievakje alleen beschikbaar is als de binnenkomende activiteit een tijdelijke tabel genereert.
Met de sectie Inbound Columns kan de gebruiker willekeurige velden uit de tabel met binnenkomende overgangen toevoegen. De geselecteerde kolommen fungeren als de sleutels in het dataobject. Het dataobject in de JSON wordt een matrixlijst met data voor geselecteerde kolommen uit elke rij van de tabel met binnenkomende overgangen.
In het tekstvak Customize parameter kunt u een geldige JSON toevoegen met aanvullende data die nodig zijn voor de externe API. Deze aanvullende data worden toegevoegd aan het parameterobject in de gegenereerde JSON.
Outbound Mapping
Op dit tabblad kunt u de JSON-voorbeeldstructuur definiëren die door de API-aanroep wordt geretourneerd.
De JSON-parser is ontworpen voor standaard typen JSON-structuurpatronen, met enkele uitzonderingen. Een voorbeeld van een standaard patroon is:{“data”:[{“key”:“value”}, {“key”:“value”},...]}
De JSON-voorbeelddefinitie moet de volgende kenmerken hebben:
- Matrixelementen moeten eigenschappen op het eerste niveau bevatten (diepere niveaus worden niet ondersteund).
Eigenschapsnamen worden uiteindelijk de kolomnamen voor het uitvoerschema van de tijdelijke uitvoertabel. - JSON-elementen die moeten worden vastgelegd, moeten zich binnen de eerste 10 nestniveaus van het JSON-antwoord bevinden.
- De kolomnaamdefinitie is gebaseerd op het eerste element van de ‘data’-matrix.
De definitie van kolommen (toevoegen/verwijderen) en de typewaarde van de eigenschap kunnen in het tabblad Column definition worden bewerkt.
Gedrag van het selectievakje Flatten:
Het selectievakje Flatten (standaard niet ingeschakeld) wordt opgegeven om aan te geven of de JSON al dan niet moet worden afgevlakt tot een sleutel-/waardetoewijzing.
-
Wanneer het selectievakje is uitgeschakeld (niet geselecteerd), wordt de voorbeeld-JSON geparseerd om naar een matrixobject te zoeken. De gebruiker moet een bijgesneden versie van de JSON-voorbeeldindeling voor API-antwoorden opgeven, zodat Adobe Campaign precies kan bepalen in welke matrix de gebruiker geïnteresseerd is. Tijdens het ontwerpen van de workflow wordt het pad naar het geneste matrixobject bepaald en opgenomen, zodat het tijdens de uitvoering kan worden gebruikt om toegang te krijgen tot het matrixobject van de JSON-antwoordtekst dat van de API-aanroep is ontvangen.
-
Wanneer het selectievakje is ingeschakeld (geselecteerd), wordt de voorbeeld-JSON afgevlakt en worden alle eigenschappen die in de opgegeven voorbeeld-JSON zijn gespecificeerd, gebruikt om kolommen van de tijdelijke uitvoertabel te maken en worden deze weergegeven op het tabblad Column definition. Als er een matrixobject in de voorbeeld-JSON voorkomt, worden alle elementen van die matrixobjecten ook afgevlakt.
Als de parsering wordt gevalideerd, verschijnt er een bericht waarin u wordt gevraagd de datatoewijzing op het tabblad Column definition aan te passen. In andere gevallen wordt een foutbericht weergegeven.
Execution
Op dit tabblad kunt u het eindpunt van de verbinding definiëren. De URL kunt u het veld HTTPS-eindpunt dat Campaign Standard zal communiceren met .
Indien nodig door het eindpunt, zijn twee types van authentificatiemethode beschikbaar:
-
Basisverificatie: voer uw gebruikersnaam-/wachtwoordgegevens in het dialoogvenster Request Header(s) sectie.
-
OAuth-verificatie: door op de knop Use connection parameters defined in an external account in een externe account kunt u een externe account selecteren waar de OAuth-verificatie is gedefinieerd. Raadpleeg de sectie Externe accounts voor meer informatie.
Properties
Op dit tabblad kunt u algemene eigenschappen voor de activiteit Externe API bepalen, zoals het weergegeven label in de gebruikersinterface. De interne id kan niet worden aangepast.
Column definition
Op het tabblad Column definition kunt u nauwkeurig de datastructuur van elke kolom opgeven om data te importeren die geen fouten bevatten en deze in overeenstemming te brengen met de typen die al aanwezig zijn in de Adobe Campaign-database voor toekomstige bewerkingen.
U kunt bijvoorbeeld het label van een kolom wijzigen, het type kolom selecteren (tekenreeks, geheel getal, datum, enzovoort) of zelfs foutverwerking opgeven.
Raadpleeg de sectie Bestand laden voor meer informatie.
Transition
Op dit tabblad kunt u de uitgaande overgang en het label ervan activeren. Deze specifieke overgang is nuttig in het geval van time-outs of als de payload de groottelimiet van data overschrijdt.
Execution options
Dit tabblad is beschikbaar voor de meeste workflowactiviteiten. Raadpleeg de sectie Activiteitseigenschappen voor meer informatie.
Testen
Als u de externe API-functionaliteit wilt testen met een eenvoudig testeindpunt, kunt u Postman Echo: https://docs.postman-echo.com gebruiken.
Problemen oplossen
Er zijn twee soorten logboekberichten die aan deze nieuwe workflowactiviteit worden toegevoegd: informatie en fouten. Ze kunnen u helpen potentiële problemen op te lossen.
Informatie
Deze logboekberichten worden gebruikt om informatie over nuttige controlepunten tijdens de uitvoering van de workflowactiviteit in een logboek te registreren.
Fouten
Deze logboekberichten worden gebruikt om informatie in een logboek te registreren over onverwachte fouten die ertoe kunnen leiden dat de workflowactiviteit mislukt.
API URL could not be parsed (error: '-2010').
Opmerking: Deze fout wordt in een logboek geregistreerd wanneer validatieregels mislukken voor de API URL.
API URL host must not be 'localhost', or IP address literal (URL host: 'localhost').
API URL host must not be 'localhost', or IP address literal (URL host: '192.168.0.5').
API URL host must not be 'localhost', or IP address literal (URL host: '[2001]').
Failed to create request body JSON. Error when adding 'params'.
Failed to create request body JSON. Error when adding 'data'.
HTTP header key is bad (header key: '%s').
Opmerking: Deze fout wordt in een logboek geregistreerd wanneer de aangepaste koptekstsleutel niet kan worden gevalideerd volgens RFC
HTTP header value is bad (header value: '%s').
Opmerking: Deze fout wordt in een logboek geregistreerd wanneer de aangepaste koptekstwaarde niet kan worden gevalideerd volgens RFC
Onjuiste JSON of onaanvaardbare indeling.
Opmerking: Dit bericht is alleen van toepassing op het parseren van de antwoordtekst van de externe API en wordt in een logboek geregistreerd bij een poging te valideren of de antwoordtekst voldoet aan de JSON-indeling die wordt voorgeschreven door deze activiteit.
When activity fails due to HTTP 401 error response - Activity failed (reason: 'HTTP - 401')
When activity fails due to a failed internal call - Activity failed (reason: 'iRc - -Nn').
When activity fails due to an invalid Content-Type header. - Activity failed (reason: 'Content-Type - application/html').