Utilizzare l’API di limitazione
L’API di limitazione ti consente di creare, configurare e monitorare le configurazioni di limitazione al fine di limitare il numero di eventi inviati al secondo.
Questa sezione fornisce informazioni globali su come lavorare con l’API. Una descrizione API dettagliata è disponibile nella documentazione delle API Adobe Journey Optimizer.
Da leggere
-
Una configurazione per organizzazione: Al momento è consentita una sola configurazione per organizzazione. È necessario definire una configurazione in una sandbox di produzione (fornita tramite
x-sandbox-name
nelle intestazioni). -
Applicazione a livello di organizzazione: Una configurazione viene applicata a livello di organizzazione.
-
Gestione dei limiti API: Al raggiungimento del limite impostato nell'API, altri eventi vengono messi in coda per un massimo di 6 ore. Impossibile modificare questo valore.
-
maxHttpConnections
parametro: Il parametro 'maxHttpConnections' è un parametro facoltativo disponibile nell'API di limitazione della velocità che consente di limitare il numero di connessioni aperte da Journey Optimizer al sistema esterno. Scopri come utilizzare l'API di limitazione di utilizzoSe desideri limitare il numero di connessioni ma anche limitare tali chiamate esterne, puoi configurare due configurazioni, una limitazione e una limitazione, sullo stesso endpoint. Entrambe le configurazioni possono coesistere per un endpoint. Per impostare 'maxHttpConnections' per un endpoint con limitazione, utilizzare l'API Throttling per impostare la soglia di limitazione e l'API Capping per impostare 'maxHttpConnections'. Quando richiami l’API di limitazione di utilizzo, puoi impostare la soglia di limitazione su un valore superiore alla soglia stessa, in modo che la regola di limitazione di utilizzo non entri in gioco.
Descrizione API di limitazione e raccolta Postman description
Nella tabella seguente sono elencati i comandi disponibili per l’API di limitazione. Informazioni dettagliate, inclusi esempi di richieste, parametri e formati di risposta, sono disponibili nella documentazione delle API di Adobe Journey Optimizer.
{uid}
/deploy{uid}
/undeploy{uid}
/canDeploy{uid}
{uid}
{uid}
Inoltre, una raccolta Postman è disponibile qui per aiutarti nella configurazione di test.
Questa raccolta è stata configurata per condividere la raccolta di variabili Postman generata tramite Integrazioni della console Adobe I/O > Prova > Scarica per Postman, che genera un file di ambiente Postman con i valori di integrazione selezionati.
Una volta scaricata e caricata in Postman, è necessario aggiungere tre variabili: {JO_HOST}
,{BASE_PATH}
e {SANDBOX_NAME}
.
{JO_HOST}
: Journey Optimizer URL gateway.{BASE_PATH}
: punto di ingresso per l'API.{SANDBOX_NAME}
: l’intestazione x-sandbox-name (ad esempio, “prod”) corrispondente al nome della sandbox in cui si svolgeranno le operazioni API. Per ulteriori informazioni, consulta la panoramica delle sandbox.
Configurazione di limitazione configuration
Di seguito è riportata la struttura di una configurazione di limitazione. Gli attributi name e description sono facoltativi.
{
"name": "<given name - free text>",
"description": "<given description - free text>"
"urlPattern": "<endpoint URL - wildcards are allowed>",
"methods": [ "<HTTP method such as GET, POST, PUT>" ],
"maxThroughput": <max call throughput>
}
Esempio:
{
"name": "throttling-config-external",
"description": "example of throttling config for an external endpoint",
"urlPattern": "https://api.example.org/data/2.5/*",
"methods": ["POST", "PUT"],
"maxThroughput": 4000
}
Errori
Durante la creazione o l’aggiornamento di una configurazione, il processo convalida la configurazione specificata e restituisce lo stato di convalida identificato dal relativo ID univoco:
"ok" or "error"
Durante la creazione, l’eliminazione o la distribuzione della configurazione di limitazione, possono verificarsi i seguenti errori:
- ERR_THROTTLING_CONFIG_100: configurazione di limitazione:
<mandatory attribute>
obbligatoria - ERR_THROTTLING_CONFIG_101: configurazione di limitazione: maxThroughput è obbligatorio e deve essere maggiore o uguale a 200 e minore o uguale a 5.000
- ERR_THROTTLING_CONFIG_104: configurazione di limitazione: formato del pattern URL non valido
- ERR_THROTTLING_CONFIG_105: configurazione di limitazione: caratteri jolly non consentiti nella parte dell’host del pattern URL
- ERR_THROTTLING_CONFIG_106: configurazione di limitazione: payload non valido
- THROTTLING_CONFIG_DELETE_FORBIDDEN_ERROR: 1456, “Impossibile eliminare una configurazione di limitazione distribuita. Annullare la distribuzione prima di eliminarla”
- THROTTLING_CONFIG_DELETE_ERROR: 1457, “Impossibile eliminare la configurazione di limitazione: si è verificato un errore imprevisto”
- THROTTLING_CONFIG_DEPLOY_ERROR: 1458, “Impossibile distribuire la configurazione di limitazione: si è verificato un errore imprevisto”
- THROTTLING_CONFIG_UNDEPLOY_ERROR: 1459, “Impossibile annullare la distribuzione della configurazione di limitazione: si è verificato un errore imprevisto”
- THROTTLING_CONFIG_GET_ERROR: 1460, “Impossibile ottenere la configurazione di limitazione: si è verificato un errore imprevisto”
- THROTTLING_CONFIG_UPDATE_NOT_ACTIVE_ERROR: 1461, “Impossibile aggiornare la configurazione di limitazione: la versione di runtime non è attiva”
- THROTTLING_CONFIG_UPDATE_ERROR: 1462, “Impossibile aggiornare la configurazione di limitazione: si è verificato un errore imprevisto”
- THROTTLING_CONFIG_NON_PROD_SANDBOX_ERROR: 1463, “Operazione non consentita nella configurazione di limitazione: sandbox non di produzione”
- THROTTLING_CONFIG_CREATE_ERROR: 1464, “Impossibile creare la configurazione di limitazione: si è verificato un errore imprevisto”
- THROTTLING_CONFIG_CREATE_LIMIT_ERROR: 1465, “Impossibile creare la configurazione di limitazione: è consentita una sola configurazione per organizzazione”
- THROTTLING_CONFIG_ALREADY_DEPLOYED_ERROR: 14466, “Impossibile distribuire la configurazione di limitazione: è già stata distribuita”
- THROTTLING_CONFIG_NOT_FOUND_ERROR: 14467, “Nessuna configurazione di limitazione trovata”
- THROTTLING_CONFIG_NOT_DEPLOYED_ERROR: 14468, “Impossibile annullare la distribuzione della configurazione di limitazione: non è ancora stata distribuita”
Esempi di errori
Quando si tenta di creare una configurazione su sandbox non di produzione:
{
"status": 400,
"error": "{\"code\":1463,\"family\":\"INPUT_OUTPUT_ERROR\",\"message\":\"Operation not allowed on throttling config: non prod sandbox\",\"service\":\"vyg-authoring-api\",\"version\":\"ed87515\",\"context\":\"com.adobe.voyager.service.authoring.restapis.v1_0.ThrottlingConfigService:384\",\"schema\":\"throttlingConfigs$ui-tests\"}",
"requestId": "5sgnAYXs8mpswwjAFEIaAU2faQYbtyHc"
}
Nel caso in cui la sandbox specificata non esiste:
{
"status": 500,
"error": "{\"code\":4000,\"family\":\"INTERNAL_ERROR\",\"message\":\"INTERNAL ERROR\",\"service\":\"vyg-authoring-api\",\"version\":\"ed87515\",\"context\":\"com.adobe.voyager.common.exceptions.ApiErrorException:43\"}",
"requestId": "04ZJ4e5ki4bYs3lfO17a7hovRGewjvdK"
}
Quando si tenta di creare un’altra configurazione:
{
"status": 400,
"error": "{\"code\":1465,\"family\":\"INPUT_OUTPUT_ERROR\",\"message\":\"Can't create throttling config: only one config allowed per org\",\"service\":\"vyg-authoring-api\",\"version\":\"ed87515\",\"context\":\"com.adobe.voyager.service.authoring.restapis.v1_0.ThrottlingConfigService:108\",\"schema\":\"throttlingConfigs$prod\"}",
"requestId": "A7ezT8JhOQT4WIAf1Fv7K2wCDA8281qM"
}
Ciclo di vita della configurazione a livello di runtime config
Quando la distribuzione di una configurazione viene annullata, questa viene contrassegnata come inattiva a livello di runtime e gli eventi in sospeso continuano a essere elaborati per 24 ore. Quindi viene eliminata nel servizio di runtime.
Una volta annullata la distribuzione di una configurazione, è possibile aggiornarla e ridistribuirla. In questo modo verrà creata una nuova configurazione di runtime che verrà considerata nell’esecuzione delle azioni successive.
Durante l’aggiornamento di una configurazione già distribuita, i nuovi valori vengono presi in considerazione immediatamente. Le risorse di sistema sottostanti vengono automaticamente adattate. Questa è una soluzione ottimale rispetto alla distribuzione e ridistribuzione della configurazione.
Esempi di risposte responses
Creazione - POST
{
"canDeploy": {
"validationStatus": "ok"
},
"createdElement": {
"name": "throttling-config-external",
"description": "example of throttling config for an external endpoint",
"urlPattern": "https://api.example.org/data/2.5/*",
"methods": [
"PUT",
"POST"
],
"maxThroughput": 4000,
"orgId": "AC202A3A5F615BD30A495FDE@AdobeOrg",
"sandboxId": "8872a010-f91e-11ea-895c-11ef8f98ba52",
"sandboxName": "prod",
"uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
"metadata": {
"createdBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
"createdById": "309F2A46640B0B300A495C83@techacct.adobe.com",
"lastModifiedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
"lastModifiedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
"createdAt": "2023-03-22T10:48:16.099647Z",
"lastModifiedAt": "2023-03-22T10:48:16.099647Z"
},
"state": "created",
"authoringFormatVersion": "1.0"
},
"uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
"uri": "/voyager/apis/throttlingConfigs/043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
"resStatus": "created"
}
Aggiornamento - PUT
{
"updatedElement": {
"_id": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6_8872a010-f91e-11ea-895c-11ef8f98ba52",
"name": "throttling-config-external -- optional",
"description": "example of throttling config for an external endpoint -- optional",
"urlPattern": "https://api.example.org/data/2.5/*",
"methods": [
"POST"
],
"maxThroughput": 5000,
"orgId": "AC202A3A5F615BD30A495FDE@AdobeOrg",
"sandboxId": "8872a010-f91e-11ea-895c-11ef8f98ba52",
"sandboxName": "prod",
"uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
"metadata": {
"createdBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
"createdById": "309F2A46640B0B300A495C83@techacct.adobe.com",
"lastModifiedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
"lastModifiedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
"createdAt": "2023-03-22T10:48:16.099647Z",
"lastModifiedAt": "2023-03-22T11:39:14.212983Z"
},
"state": "updated",
"authoringFormatVersion": "1.0",
"hasBeenDeployed": false
},
"uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
"uri": "/voyager/apis/throttlingConfigs/043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
"resStatus": "updated",
"canDeploy": {
"validationStatus": "ok"
}
}
Lettura (dopo l’aggiornamento) - GET
{
"result": {
"_id": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6_8872a010-f91e-11ea-895c-11ef8f98ba52",
"name": "throttling-config-external -- optional",
"description": "example of throttling config for an external endpoint -- optional",
"urlPattern": "https://api.example.org/data/2.5/*",
"methods": [
"POST"
],
"maxThroughput": 5000,
"orgId": "AC202A3A5F615BD30A495FDE@AdobeOrg",
"sandboxId": "8872a010-f91e-11ea-895c-11ef8f98ba52",
"sandboxName": "prod",
"uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
"metadata": {
"createdBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
"createdById": "309F2A46640B0B300A495C83@techacct.adobe.com",
"lastModifiedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
"lastModifiedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
"createdAt": "2023-03-22T10:48:16.099647Z",
"lastModifiedAt": "2023-03-22T11:39:14.212983Z"
},
"state": "updated",
"authoringFormatVersion": "1.0",
"hasBeenDeployed": false
}
}
Lettura (dopo la distribuzione) - GET
{
"result": {
"_id": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6_8872a010-f91e-11ea-895c-11ef8f98ba52",
"orgId": "AC202A3A5F615BD30A495FDE@AdobeOrg",
"sandboxId": "8872a010-f91e-11ea-895c-11ef8f98ba52",
"sandboxName": "prod",
"uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
"urlPattern": "https://api.example.org/data/2.5/*",
"methods": [
"POST"
],
"maxThroughput": 5000,
"authoringFormatVersion": "1.0",
"name": "throttling-config-external -- optional",
"description": "example of throttling config for an external endpoint -- optional",
"version": "1.0",
"state": "deployed",
"metadata": {
"createdBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
"createdById": "309F2A46640B0B300A495C83@techacct.adobe.com",
"createdAt": "2023-03-22T10:48:16.099647Z",
"lastModifiedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
"lastModifiedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
"lastModifiedAt": "2023-03-22T11:39:14.212983Z",
"lastDeployedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
"lastDeployedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
"lastDeployedAt": "2023-03-22T11:46:07.532648Z"
},
"hasBeenDeployed": true
}
}
Casi d’uso uc
In questa sezione sono elencati i casi d'uso chiave per la gestione delle configurazioni di limitazione in Journey Optimizer e i comandi API associati necessari per implementare il caso d'uso.
I dettagli su ciascun comando API sono disponibili nella descrizione API e raccolta Postman.
Chiamate API per l’utilizzo di:
list
- Recupera le configurazioni esistenti.create
- Crea una nuova configurazione.candeploy
- Controlla se la configurazione può essere distribuita.deploy
- Distribuisce la configurazione.
Chiamate API per l’utilizzo di:
list
- Recupera le configurazioni esistenti.get
- Recupera i dettagli di una configurazione specifica.update
- Modifica la configurazione.candeploy
- Verifica l'idoneità alla distribuzione.deploy
- Distribuisce la configurazione.
Chiamate API per l’utilizzo di:
list
- Recupera le configurazioni esistenti.undeploy
- Annulla la distribuzione della configurazione.delete
- Rimuove la configurazione.
In una sola chiamata API è possibile annullare la distribuzione ed eliminare la configurazione utilizzando il parametro forceDelete
.
Chiamate API per l’utilizzo di:
list
- Recupera le configurazioni esistenti.delete
(con il parametroforceDelete
) - Forza l'eliminazione di una configurazione distribuita in un singolo passaggio.
note note |
---|
NOTE |
Non è richiesto annullare la distribuzione della configurazione prima dell’aggiornamento |
Chiamate API per l’utilizzo di:
list
- Recupera le configurazioni esistenti.get
- Recupera i dettagli di una configurazione specifica.update
- Modifica la configurazione.