Utilizzo dell’API Capping

Introduzione

Journey OrchestrationLe API API di Microsoft supportano 5000 eventi/secondi, ma alcuni sistemi o API esterni non possono avere un throughput equivalente. Ecco perché Journey Orchestration viene fornito con una funzione dedicata denominata API di cattura per monitorare e limitare la velocità che imponiamo ai sistemi esterni.

Durante una configurazione dell'origine dati, definirai una connessione a un sistema per recuperare informazioni aggiuntive che verranno utilizzate nei tuoi viaggi, o per una definizione dell'azione, configurerai la connessione di un sistema di terze parti per inviare messaggi o chiamate API. Ogni volta che una chiamata API viene eseguita da Journey, l'API di capping viene interrogata, la chiamata viene eseguita tramite il motore API. In presenza di un limite definito, la chiamata viene rifiutata e il sistema esterno non verrà sovraccaricato.

Per ulteriori informazioni sulla configurazione delle azioni o delle origini dati, vedere Informazioni sulle azioni o Informazioni sulle origini dati

Resources

Per utilizzare questa API con l'istanza Journey Orchestration, è necessario utilizzare la console AdobeI/O. Per iniziare, seguire la Guida introduttiva a Adobe Developer Console e utilizzare le sezioni presenti in questa pagina.

Per verificare e preparare l'integrazione, è disponibile una raccolta Postman qui.

Autenticazione

Impostazione dell’accesso API

Journey Orchestration L'accesso alle API è configurato tramite i passaggi descritti di seguito. Ciascuno di questi passaggi è descritto nella documentazione Adobe I/O.

1. Verificate di disporre di un certificato digitale oppure createne uno, se necessario. Le chiavi pubblica e privata fornite con il certificato sono necessarie nei seguenti passaggi.
2. Crea una nuova integrazione con Journey Orchestration Servicein Adobe I/O e configurala. L'accesso al profilo di prodotto è necessario per Journey Orchestration e Adobe Experience Platform. Le credenziali verranno quindi generate (Chiave API, Segreto cliente…).
3. Create un token Web JSON (JWT) dalle credenziali generate in precedenza e firmatelo con la vostra chiave privata. Il JWT codifica tutte le informazioni di identità e sicurezza necessarie per Adobe per verificare la propria identità e concedere l'accesso all'API. Questo passaggio è dettagliato in questa sezione sezione
4. Scambiare il JWT per un Token di accesso tramite una richiesta di POST o tramite l'interfaccia della console per sviluppatori. Questo token di accesso dovrà essere utilizzato in ogni intestazione delle richieste API.

Per stabilire una sessione di servizio sicura Adobe I/O API, ogni richiesta a un servizio Adobe deve includere nell’intestazione Autorizzazione le informazioni riportate di seguito.

curl -X GET https://journey.adobe.io/authoring/XXX \
 -H 'Authorization: Bearer <ACCESS_TOKEN>' \
 -H 'x-api-key: <API_KEY>' \
 -H 'x-gw-ims-org-id: <ORGANIZATION>'

• <organization>: Si tratta dell’ID organizzazione personale, un ID organizzazione viene fornito dal Adobe per ogni istanza:

  • <organization> : l'istanza di produzione

  Per ottenere il valore ID ORGANIZZAZIONE, rivolgiti all’amministratore o al contatto tecnico Adobe. È inoltre possibile recuperarlo in Adobe I/O quando si crea una nuova integrazione, nell’elenco delle licenze (vedere la documentazione Adobe I/O).

• <access_token>: Token di accesso personale, che è stato recuperato durante lo scambio del JWT tramite una richiesta di POST.

• <api_key>: la chiave API personale. Viene fornito in Adobe I/O dopo la creazione di una nuova integrazione in Journey Orchestration Service.

Capping della descrizione API

L’API Capping consente di creare, configurare e monitorare le configurazioni di capping.

Metodo	Percorso	Descrizione
POST	list/endpointConfigs	Ottenere un elenco delle configurazioni di capping dell'endpoint
POST	/endpointConfigs	Creare una configurazione di cappottatura dell'endpoint
POST	/endpointConfigs/{uid}/deploying	Implementare una configurazione di cappottatura dell'endpoint
POST	/endpointConfigs/{uid}/undeployment	Disdistribuire una configurazione di cappottatura dell'endpoint
POST	/endpointConfigs/{uid}/canDeploy	Verificate se è possibile distribuire o meno una configurazione di cappotto dell'endpoint
PUT	/endpointConfigs/{uid}	Aggiornare una configurazione di cappottatura dell'endpoint
GET	/endpointConfigs/{uid}	Recuperare una configurazione di capping endpoint
DELETE	/endpointConfigs/{uid}	Eliminare una configurazione di codifica enpoint

Quando si crea o aggiorna una configurazione, viene automaticamente eseguito un controllo per garantire la sintassi e l'integrità del payload.
In caso di problemi, l'operazione restituisce un avviso o degli errori per facilitare la correzione della configurazione.

Configurazione endpoint

Di seguito è riportata la struttura di base di una configurazione di endpoint:

{
    "url": "<endpoint URL>",  //wildcards are allowed in the endpoint URL
    "methods": [ "<HTTP method such as GET, POST, >, ...],
    "services": {
        "<service name>": { . //must be "action" or "dataSource" 
            "maxHttpConnections": <max connections count to the endpoint>
            "rating": {          
                "maxCallsCount": <max calls to be performed in the period defined by period/timeUnit>,
                "periodInMs": <integer value greater than 0>
            }
        },
        ...
    }
}

Esempio:

`{
  "url": "https://api.example.org/data/2.5/*",
  "methods": [
    "GET"
  ],
  "services": {
    "dataSource": {
      "maxHttpConnections": 30000,
      "rating": {
        "maxCallsCount": 5000,
        "periodInMs": 1000
      }
    }
  },
  "orgId": "<IMS Org Id>"
}

Avvisi ed errori

Quando viene chiamato un metodo canDeploy, il processo convalida la configurazione e restituisce lo stato di convalida identificato dal relativo ID univoco:

"ok" or "error"

Gli errori potenziali sono:

• ERR_ENDPOINTCONFIG_100: configurazione di capping: url mancante o non valido
• ERR_ENDPOINTCONFIG_101: configurazione di capping: url non valido
• ERR_ENDPOINTCONFIG_102: configurazione di capping: url non valido: il carattere jolly nell'URL non è consentito in host:port
• ERR_ENDPOINTCONFIG_103: configurazione di capping: metodi HTTP mancanti
• ERR_ENDPOINTCONFIG_104: configurazione di capping: nessuna classificazione di chiamata definita
• ERR_ENDPOINTCONFIG_107: configurazione di capping: numero massimo di chiamate non valido (maxCallsCount)
• ERR_ENDPOINTCONFIG_108: configurazione di capping: numero massimo di chiamate non valido (puntoInMs)
• ERR_ENDPOINTCONFIG_111: configurazione di capping: impossibile creare la configurazione dell'endpoint: payload non valido
• ERR_ENDPOINTCONFIG_112: configurazione di capping: impossibile creare la configurazione dell'endpoint: attesa di un payload JSON
• ERR_AUTHORING_ENDPOINTCONFIG_1: nome servizio non valido <!--<given value>-->: deve essere 'dataSource' o 'action'

L'avviso potenziale è il seguente:

ERR_ENDPOINTCONFIG_106: configurazione di capping: max connessioni HTTP non definite: nessuna limitazione per impostazione predefinita

Casi di utilizzo

In questa sezione sono elencati i cinque casi d'uso principali che è possibile eseguire per gestire la configurazione di capping in Journey Orchestration.

Per facilitare il test e la configurazione, è disponibile una raccolta Postman qui.

Questa raccolta Postman è stata impostata per condividere la raccolta Postman Variable generata tramite Adobe I/O Console's Integrations > Try it out > Download for Postman, che genera un file Postman Environment con i valori di integrazioni selezionati.

Una volta scaricati e caricati in Postman, è necessario aggiungere tre variabili: {JO_HOST},{Base_Path} e {SANDBOX_NAME}.

• {JO_HOST} : Journey Orchestration URL gateway
• {BASE_PATH} : punto di ingresso per l'API. Il valore è '/authoring'
• {SANDBOX_NAME} : l’intestazione x-sandbox-name (ad esempio, 'prod') corrispondente al nome della sandbox in cui avranno luogo le operazioni API. Per ulteriori informazioni, consultate la panoramica sulle sandbox.

Nella sezione seguente, troverete l'elenco delle chiamate API rimanenti ordinate per eseguire il caso d'uso.

Caso d’uso n° 1: Creazione e implementazione di una nuova configurazione di capping

1. list
2. create
3. canonizzare
4. distribuire

Caso d’uso n°2: Aggiornare e distribuire una configurazione di caption non ancora distribuita

1. list
2. get
3. update
4. canonizzare
5. distribuire

Caso d’uso n° 3: Disdistribuire ed eliminare una configurazione di caption distribuita

1. list
2. non distribuire
3. delete

Caso d’uso n°4: Eliminare una configurazione di tappatura distribuita.

In una sola chiamata API, potete annullare la distribuzione ed eliminare la configurazione utilizzando il parametro forceDelete.

1. list
2. delete, with forceDelete param

Caso d’uso n° 5: Aggiornamento di una configurazione di tappatura già implementata

1. list
2. get
3. update
4. non distribuire
5. canonizzare
6. distribuire