Attività External API external-api

Descrizione description

L’attività External API porta dati nel flusso di lavoro da un sistema esterno tramite una chiamata API HTTP.

Gli endpoint di sistema esterni possono essere endpoint API pubblici, sistemi di gestione dei clienti o istanze di applicazioni senza server (ad esempio, Adobe I/O Runtime), per citare alcune categorie.

NOTE
Per motivi di sicurezza, l’utilizzo di JSSP non è supportato in Campaign Standard. Se devi eseguire del codice, puoi richiamare un’istanza Adobe I/O Runtime tramite l’attività External API.

Le principali caratteristiche di questa attività sono:

  • Possibilità di trasmettere dati in formato JSON a un endpoint REST API di terze parti
  • Possibilità di ricevere una risposta JSON, mapparla sulle tabelle di output e passare a valle ad altre attività del flusso di lavoro.
  • Gestione degli errori con una transizione specifica in uscita

Avvisi di compatibilità con versioni precedenti from-beta-to-ga

Con la versione di Campaign Standard 20.4, il limite di dimensione dei dati di risposta http e le protezioni del timeout di risposta sono stati ridotti per allinearli alle best practice - consulta Limitazioni e protezioni. Queste modifiche delle limitazioni non avranno effetto sulle attività External API già esistenti; pertanto, si consiglia di sostituire queste ultime con nuove versioni in tutti i flussi di lavoro.

Durante la sostituzione delle attività External API, aggiungi la nuova attività External API al flusso di lavoro, copia manualmente i dettagli di configurazione, quindi elimina la vecchia attività.

NOTE
Non potrai copiare i valori di intestazione per attività specifiche poiché sono nascosti all’interno dell’attività.

Limitazioni e protezioni guardrails

Questa attività è soggetta ai seguenti guardrail:

  • Limite di dimensione dei dati di risposta HTTP di 5 MB (nota: si tratta di una modifica rispetto al limite di 50 MB della versione precedente)
  • Timeout della richiesta: 1 minuto (nota: rispetto alla versione precedente, che prevedeva un timeout di 10 minuti, è stata apportata questa modifica)
  • I reindirizzamenti HTTP non sono consentiti
  • Gli URL non HTTPS vengono rifiutati
  • L’intestazione di richiesta "Accept: application/json" e l’intestazione di risposta "Content-Type: application/json" sono consentite

Sono stati introdotti guardrail specifici:

  • Profondità massima JSON: limita la profondità massima di un JSON nidificato personalizzato che può essere elaborato a 10 livelli.
  • Lunghezza massima chiave JSON: limita a 255 la lunghezza massima della chiave interna generata. Questa chiave è associata all’ID di colonna.
  • Numero massimo di chiavi duplicate JSON consentite: limita a 150 il numero totale massimo di nomi di proprietà JSON duplicati, utilizzati come ID di colonna.
CAUTION
L’attività External API è destinata al recupero di dati a livello di campagna (set di offerte più recenti, punteggi più recenti, ecc.), non al recupero di informazioni specifiche per ciascun profilo, in quanto ciò può comportare il trasferimento di grandi quantità di dati. Se il caso di utilizzo lo richiede, si consiglia di utilizzare l’attività Transfer file.

Configurazione configuration

Trascina e rilascia un’attività External API nel flusso di lavoro e apri l’attività per avviare la configurazione.

Inbound Mapping

Inbound Mapping è una tabella temporanea generata da un’attività in entrata precedente che verrà visualizzata e inviata come JSON nell’interfaccia utente.
In base a questa tabella temporanea, l’utente può apportare modifiche ai dati in entrata.

Il menu a discesa Inbound resource ti consente di selezionare l’attività di query che creerà la tabella temporanea.

La casella di controllo Add count parameter aggiungerà un valore di conteggio per ogni riga proveniente dalla tabella temporanea. Tieni presente che questa casella di controllo è disponibile solo se l’attività in entrata genera una tabella temporanea.

La sezione Inbound Columns consente all’utente di aggiungere qualsiasi campo dalla tabella di transizione in entrata. Le colonne selezionate saranno le chiavi nell’oggetto dati. L’oggetto dati nel JSON sarà un elenco array contenente dati per le colonne selezionate da ogni riga della tabella di transizione in entrata.

La casella di testo Customize parameter ti consente di aggiungere un JSON valido con dati aggiuntivi richiesti dall’API esterna. Questi dati aggiuntivi verranno aggiunti all’oggetto params nel JSON generato.

Outbound Mapping

Questa scheda ti consente di definire la struttura JSON campione restituita dalla chiamata API.

Il parser JSON è progettato per accogliere tipi di pattern di struttura JSON standard, con alcune eccezioni. Un esempio di pattern standard è:{“data”:[{“key”:“value”}, {“key”:“value”},...]}

La definizione JSON campione deve avere le seguenti caratteristiche:

  • Gli elementi array devono contenere proprietà di primo livello (i livelli più profondi non sono supportati).
    I nomi delle proprietà finiranno per diventare nomi di colonna per lo schema di output della tabella temporanea di output.
  • Gli elementi JSON da acquisire devono essere a 10 o meno livelli di nidificazione nella risposta JSON.
  • La definizione del nome della colonna si basa sul primo elemento dell’array "dati".
    La definizione delle colonne (aggiungere/rimuovere) e il valore del tipo della proprietà possono essere modificati nella scheda Column definition.

Comportamento della casella di controllo Flatten:

La casella di controllo Flatten (impostazione predefinita: deselezionata) viene fornita per indicare se appiattire o meno il JSON a una mappa chiave/valore.

  • Quando la casella di controllo è disattivata (deselezionata), il JSON campione viene analizzato per cercare un oggetto array. L’utente dovrà fornire una versione ridotta del formato JSON campione della risposta API in modo tale che Adobe Campaign possa determinare esattamente quale array gli utenti sono interessati a utilizzare. Al momento dell’authoring del flusso di lavoro, il percorso dell’oggetto array nidificato verrà determinato e registrato, in modo tale che possa essere utilizzato al momento dell’esecuzione per accedere all’oggetto array dal corpo della risposta JSON ricevuto dalla chiamata API.

  • Quando la casella di controllo è attivata (selezionata), il JSON campione verrà appiattito e tutte le proprietà specificate nel JSON campione fornito verranno utilizzate per creare colonne della tabella temporanea di output e visualizzate nella scheda Column definitions. Tieni presente che se nel JSON campione sono presenti oggetti array, anche tutti gli elementi di tali oggetti array verranno appiattiti.

Se l’analisi viene convalidata, viene visualizzato un messaggio che ti invita a personalizzare la mappatura dei dati nella scheda "Column definition". In altri casi, viene visualizzato un messaggio di errore.

Execution

Questa scheda consente di definire l’endpoint di connessione. Il URL consente di definire il Endpoint HTTP quel Campaign Standard comunicherà con.

Se necessario per l’endpoint, sono disponibili due tipi di metodi di autenticazione:

  • Autenticazione di base: immetti il nome utente/password nella Request Header(s) sezione.

  • Autenticazione OAuth: facendo clic sul pulsante Use connection parameters defined in an external account in un account esterno, puoi selezionare un account esterno in cui è definita l’autenticazione OAuth. Per ulteriori informazioni, consulta la sezione Account esterni.

Properties

Questa scheda ti consente di controllare le proprietà generali dell’attività External API, come l’etichetta visualizzata nell’interfaccia utente. L’ID interno non è personalizzabile.

Column definition

NOTE
Questa scheda viene visualizzata quando il formato dei dati di risposta viene completato e convalidato nella scheda Outbound Mapping.

La scheda Column definition ti consente di specificare con precisione la struttura dati di ogni colonna al fine di importare dati che non contengono errori e di farli corrispondere ai tipi già presenti nel database di Adobe Campaign per le operazioni future.

Ad esempio, puoi modificare l’etichetta di una colonna, selezionarne il tipo (stringa, numero intero, data, ecc.) o anche specificare l’elaborazione degli errori.

Per ulteriori informazioni, consulta la sezione Load file.

Transition

Questa scheda ti consente di attivare la transizione in uscita e la relativa etichetta. Questa transizione specifica è utile in caso di timeout o se il payload supera il limite di dimensione dei dati.

Execution options

Questa scheda è disponibile nella maggior parte delle attività del flusso di lavoro. Per ulteriori informazioni, consulta la sezione Proprietà delle attività.

Test

Per testare la funzionalità External API con un semplice endpoint di test, puoi utilizzare Postman Echo: https://docs.postman-echo.com.

Risoluzione dei problemi

Esistono due tipi di messaggi di log aggiunti a questa nuova attività del flusso di lavoro: informazioni ed errori. Possono essere utili per risolvere eventuali problemi.

Informazioni

Questi messaggi di log vengono utilizzati per registrare informazioni su punti di controllo utili durante l’esecuzione dell’attività del flusso di lavoro.

Formato del messaggio
Esempio
Invoking API URL '%s'.
Richiamo dell’URL API “https://example.com/api/v1/web-coupon?count=2”.
Retrying API URL '%s' due to %s in %d ms, attempt %d.
Nuovo tentativo URL API 'https://example.com/api/v1/web-coupon?count=0' a causa di HTTP - 401 in 2364 ms, tentativo 2.
Transferring content from '%s' (%s / %s).
Trasferimento di contenuto da “https://example.com/api/v1/web-coupon?count=2” (1234 / 1234).
Using cached access token for provider ID '%s'.
Utilizzo del token di accesso nella versione cache per l’ID provider 'EXT25'. Nota: EXT25 è l’ID (o nome) dell’account esterno.
Fetched access token from server for provider ID '%s'.
Token di accesso recuperato dal server per l’ID provider 'EXT25'. Nota: EXT25 è l’ID (o nome) dell’account esterno.
Refreshing OAuth access token due to error (HTTP: '%d').
Aggiornamento del token di accesso OAuth a causa di un errore (HTTP: '401').
Error refreshing OAuth access token (error: '%d').
Errore durante l’aggiornamento del token di accesso OAuth (errore: '404').
Failed to fetch the OAuth access token using the specified external account on attempt %d, retrying in %d ms.
Impossibile recuperare il token di accesso OAuth utilizzando l’account esterno specificato al tentativo 1. Verrà eseguito un nuovo tentativo tra 1387 ms.

Errori

Questi messaggi di log vengono utilizzati per registrare informazioni su condizioni di errore impreviste, che possono impedire il funzionamento dell’attività del flusso di lavoro.

Codice - Formato del messaggio
Esempio
WKF-560250 - API request body exceeded limit (limit: '%d').
Il corpo della richiesta API ha superato il limite (limite: “5242880”).
WKF-560239 - API response exceeded limit (limit: '%d').
La risposta API ha superato il limite (limite: “5242880”).
WKF-560245 - API URL could not be parsed (error: '%d').

Impossibile analizzare l’URL API (errore: “-2010”).

Nota: questo errore viene registrato quando l’URL API non rispetta le regole di convalida.

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

L’host dell’URL API non deve essere “localhost” o indirizzo IP letterale (Host URL: “localhost”).

L’host dell’URL API non deve essere “localhost” o indirizzo IP letterale (Host URL: “192.168.0.5”).

L’host dell’URL API non deve essere “localhost” o indirizzo IP letterale (Host URL: “[2001]”).

WKF-560238 - API URL must be a secure URL (https) (requested URL: '%s').
L’URL API deve essere un URL protetto (https) (URL richiesto: “https://example.com/api/v1/web-coupon?count=2”).
WKF-560249 - Impossibile creare il corpo della richiesta JSON. Error when adding '%s'.

Impossibile creare il corpo della richiesta JSON. Errore durante l’aggiunta di “params”.

Impossibile creare il corpo della richiesta JSON. Errore durante l’aggiunta di “data”.

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

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

Nota: questo errore viene registrato quando la chiave di intestazione personalizzata non supera la convalida secondo la RFC

WKF-560248 - HTTP header key is not allowed (header key: '%s').
Chiave di intestazione HTTP non consentita (chiave di intestazione: “Accept”).
WKF-560247 - Valore di intestazione HTTP non valido (valore di intestazione: "%s").

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

Nota: questo errore viene registrato quando il valore di intestazione personalizzato non supera la convalida secondo la RFC

WKF-560240 - JSON payload has bad property '%s'.
Il payload JSON ha una proprietà non valida “blah”.
WKF-560241 - Malformed JSON or unacceptable format.

JSON malformato o formato non accettabile.

Nota: questo messaggio si applica solo all’analisi del corpo della risposta dall’API esterna e viene registrato quando si tenta di convalidare la conformità del corpo della risposta al formato JSON richiesto da questa attività.

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

Quando l’attività non riesce a causa di una risposta di errore HTTP 401 - Attività non riuscita (motivo: “HTTP - 401”)

Quando l’attività non riesce a causa di una chiamata interna non riuscita - Attività non riuscita (motivo: “iRc - -Nn”).

Quando l’attività non riesce a causa di un’intestazione Content-Type non valida. - Attività non riuscita (motivo: “Content-Type - application/html”).

WKF-560278 - "Error initializing OAuth helper (error: '%d')" .
Questo errore indica che, a causa di un errore nell’utilizzo degli attributi configurati nell’account esterno per inizializzare l’helper, l’attività non è riuscita a inizializzare la funzionalità interna helper OAuth2.0.
WKF-560279 - "HTTP header key is not allowed (header key: '%s')."
Questo messaggio di avviso (non di errore) indica che l’account esterno OAuth 2.0 è stato configurato per aggiungere una credenziale come intestazione HTTP, ma la chiave di intestazione utilizzata non è consentita perché riservata.
WKF-560280 - External account of '%s' ID cannot be found.
Impossibile trovare l’account esterno dell’ID 'EXT25'. Nota: questo errore indica che l’attività è configurata per utilizzare un account esterno che non è più possibile trovare. È molto probabile che ciò avvenga quando l’account è stato cancellato dal DB, e per questo motivo non dovrebbe accadere in normali circostanze operative.
WKF-560281 - External account of '%s' ID is disabled.
L’account esterno dell’ID 'EXT25' è disabilitato. Nota: questo errore indica che l’attività è configurata per l’utilizzo di un account esterno che però è stato disabilitato (o contrassegnato come inattivo).
WKF-560282 - Protocol not supported.
Questo errore indica che l’account esterno associato all’attività non è un account esterno OAuth2.0. Per questo motivo è improbabile che questo errore si verifichi, a meno che non si verifichino alcuni danneggiamenti o modifiche manuali alla configurazione dell’attività.
WKF-560283 - Failed to fetch the OAuth access token.
La causa più comune di questo errore è la configurazione errata dell’account esterno (ad esempio l’utilizzo dell’account esterno senza verificare che la connessione abbia esito positivo). È possibile che le URL/credenziali sull’account esterno vengano modificate.
CRL-290199 - Cannot reach page at: %s.
Questo messaggio di errore viene visualizzato nella schermata dell’interfaccia utente degli account esterni durante la configurazione per OAuth. Ciò significa che l’URL del server di autorizzazione esterno è errato/modificato o che non è disponibile la risposta dal server.
CRL-290200 - Incomplete/Incorrect credentials.
Questo messaggio di errore viene visualizzato nella schermata dell’interfaccia utente degli account esterni durante la configurazione per OAuth. Ciò significa che le credenziali non sono corrette o che ne mancano altre necessarie per connettersi al server di autenticazione.
recommendation-more-help
3ef63344-7f3d-48f9-85ed-02bf569c4fff