Configurare le notifiche utilizzando i webhook

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X. info

Che cos'è un webhook?

Un webhook definisce un gestore di callback HTTP attivato da un evento. In alternativa all'utilizzo dei modelli di notifica sulla monetizzazione, puoi creare webhook e configurarli per la gestione delle notifiche degli eventi, come descritto in Configurare le notifiche utilizzando i modelli di notifica.

Per configurare le notifiche utilizzando i webhook, completa i seguenti passaggi utilizzando l'interfaccia utente di Edge Management o l'API Management and Monetization:

  1. Aggiungi webhook che definiscono i gestori di callback per gli eventi di notifica utilizzando l'interfaccia utente o l'API.
  2. Configura il gestore del callback.
  3. Configura la notifica per un piano tariffario regolabile utilizzando l'interfaccia utente o l'API.

Gestione dei webhook

Aggiungi e gestisci i webhook che definiscono i gestori dei callback per gli eventi di notifica utilizzando la UI o l'API.

Gestione degli webhook tramite l'interfaccia utente

Aggiungi e gestisci gli webhook che definiscono i gestori dei callback per gli eventi di notifica utilizzando l'interfaccia utente, come descritto nelle sezioni seguenti.

Esplorazione della pagina Webhook

Accedi alla pagina Webhook, come descritto di seguito.

Edge

Per accedere alla pagina Webhook utilizzando l'interfaccia utente di Edge:

  1. Accedi ad apigee.com/edge.
  2. Seleziona Pubblica > Monetizzazione > Webhook nella barra di navigazione a sinistra.

Viene visualizzata la pagina Webhook.

Come evidenziato nella figura, la pagina Webhook ti consente di:

Edge classico (private cloud)

Per accedere alla pagina Webhook utilizzando l'interfaccia utente Edge classica:

  1. Accedi a http://ms-ip:9000, dove ms-ip è l'indirizzo IP o il nome DNS del nodo del server di gestione.

  2. Seleziona Amministrazione > Webhook.

Viene visualizzata la pagina Webhook.

La pagina Webhook ti consente di:

Aggiunta di un webhook utilizzando l'interfaccia utente

Per aggiungere un webhook utilizzando l'interfaccia utente:

  1. Accedi alla pagina webhook.
  2. Fai clic su + Webhook.
  3. Inserisci le seguenti informazioni (tutti i campi sono obbligatori).
    Campo Descrizione
    Nome Nome del webhook.
    URL URL del gestore del callback che verrà chiamato quando viene attivata la notifica dell'evento. Consulta Configurare il gestore del callback.
  4. Fai clic su Salva.

Il webhook viene aggiunto all'elenco e attivato per impostazione predefinita.

Modificare un webhook utilizzando l'interfaccia utente

Per modificare un webhook utilizzando l'interfaccia utente:

  1. Accedi alla pagina webhook.
  2. Posiziona il cursore sopra l'webhook da modificare e fai clic su nel menu delle azioni.
  3. Modifica i campi del webhook, se necessario.
  4. Fai clic su Aggiorna webhook.

Attivazione o disattivazione di un webhook tramite l'interfaccia utente

Per attivare o disattivare un webhook utilizzando l'interfaccia utente:

  1. Accedi alla pagina Webhook.
  2. Posiziona il cursore del mouse sul webhook e attiva/disattiva l'opzione di stato.

Eliminazione di un webhook utilizzando l'interfaccia utente

Per eliminare un webhook utilizzando l'interfaccia utente:

  1. Accedi alla pagina Webhook.
  2. Posiziona il cursore sopra l'webhook che vuoi eliminare e fai clic su .

Il webhook viene eliminato e rimosso dall'elenco.

Gestione degli webhook utilizzando l'API

Aggiungi e gestisci gli webhook utilizzando l'API come descritto nelle sezioni seguenti.

Visualizzazione di tutti i webhook utilizzando l'API

Visualizza tutti i webhook inviando una richiesta GET a /mint/organizations/{org_name}/webhooks. Ad esempio:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

Di seguito è riportato un esempio della risposta restituita:

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

Visualizzazione di un webhook mediante l'API

Visualizza un singolo webhook inviando una richiesta GET a /mint/organizations/{org_name}/webhooks/{webhook_id}.

Ad esempio:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Di seguito è riportato un esempio di risposta:

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

Aggiunta di un webhook tramite l'API

Aggiungi un webhook inviando una richiesta POST a /mint/organizations/{org_name}/webhooks. Devi trasmettere il nome del webhook e l'URL del gestore di callback che verrà chiamato quando viene attivata la notifica dell'evento.

Ad esempio, di seguito viene creato un webhook denominato webhook3 e assegna callbackhandler3 al webhook:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

Di seguito viene fornito un esempio della risposta:

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Modificare un webhook utilizzando l'API

Modifica un webhook inviando una richiesta PUT a /mint/organizations/{org_name}/webhooks/{webhook_id}. Passa gli aggiornamenti nel corpo della richiesta.

Ad esempio, il seguente aggiorna il gestore del callback associato a webhook1:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

Di seguito viene fornito un esempio della risposta:

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Attivazione o disattivazione di un webhook tramite l'API

Attiva o disattiva un webhook inviando una richiesta POST a /mint/organizations/{org_name}/webhooks/{webhook_id}, come hai fatto per aggiornare un webhook, e imposta l'attributo enabled nel corpo della richiesta su true o false, rispettivamente. Se disattivi il webhook, non verrà attivato quando si verifica un evento.

Ad esempio, quanto segue abilita webhook3:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

Di seguito viene fornito un esempio della risposta:

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Eliminazione di un webhook utilizzando l'API

Elimina un webhook inviando una richiesta DELETE a /mint/organizations/{org_name}/webhooks/{webhook_id}.

Per specificare se forzare o meno l'eliminazione dell'webhook se sono in corso processi, imposta il parametro di query forceDelete su true o false. Il parametro di query forceDelete è abilitato (true) per impostazione predefinita.

Ad esempio, quanto segue elimina webhook3:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Configurazione del gestore di callback

Di seguito è riportato il formato della richiesta JSON inviata al gestore del callback definito da un webhook quando viene attivata una notifica di evento. Devi assicurarti che l'handler callback elabori la richiesta in modo appropriato.

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

Configurare le notifiche per un piano tariffario variabile

Configura le notifiche utilizzando gli webhook per un piano tariffario regolabile tramite l'interfaccia utente o l'API.

Configurazione delle notifiche per un piano tariffario variabile utilizzando l'interfaccia utente

Configura le notifiche utilizzando gli webhook per un piano tariffario regolabile tramite l'interfaccia utente, come descritto di seguito.

Accedere alla finestra di dialogo Notifiche per un piano tariffario regolabile

Accedi alla finestra di dialogo Notifiche per un piano tariffario variabile, come descritto di seguito.

Edge

Per accedere alla finestra di dialogo delle notifiche utilizzando la UI Edge:

  1. Crea e pubblica un piano di frequenza delle notifiche regolabile, come descritto in Specificare dettagli del piano di frequenza delle notifiche regolabile.
  2. Accedi alla pagina Tariffe selezionando Pubblicazione > Monetizzazione > Tariffe nella barra di navigazione a sinistra.
  3. Posiziona il cursore del mouse sopra il piano di frequenza delle notifiche regolabile pubblicato per visualizzare le azioni.
  4. Fai clic su +Avvisa.

    Viene visualizzata la finestra di dialogo Notifiche.

    Nota: il piano tariffario deve essere pubblicato affinché l'azione +Avvisa venga visualizzata.

Edge classico (private cloud)

Per accedere alla pagina Notifiche:

  1. Crea un piano tariffario delle notifiche regolabile, come descritto in Specificare dettagli del piano di notifica regolabile.
  2. Seleziona Pubblica > Pacchetti per visualizzare i piani tariffari.
  3. Fai clic su +Avvisa nella colonna Azioni per il piano tariffario.

    Viene visualizzata la finestra di dialogo Notifiche.

Aggiunta di notifiche per un piano tariffario regolabile utilizzando l'interfaccia utente

Per aggiungere notifiche per un piano tariffario regolabile nell'interfaccia utente:

  1. Accedi alla finestra di dialogo Notifiche.
  2. Imposta la condizione di notifica in Intervalli di notifica specificando una percentuale del numero di transazioni di destinazione in cui attivare una notifica. In particolare:
    • Per impostare una percentuale esatta, inseriscila nel campo A/Da % e lascia vuoto il campo A %.
    • Per impostare un intervallo percentuale, inserisci la percentuale iniziale e finale rispettivamente nei campi At/Da % e A % e un valore di incremento nel campo %passaggio. Per impostazione predefinita, le notifiche vengono inviate con incrementi del 10% nell'intervallo specificato.

    Il campo Notify At viene aggiornato in base a ogni percentuale del numero di transazioni di destinazione che attiverà un evento.

  3. Per impostare condizioni di notifica aggiuntive, fai clic su + Aggiungi e ripeti il passaggio 4.
  4. Imposta l'azione di notifica in Webhook selezionando uno o più webhook per gestire la gestione dei callback quando vengono attivate le notifiche.
  5. Fai clic su Crea notifica.

Modificare le notifiche per un piano tariffario regolabile utilizzando l'interfaccia utente

Per modificare le notifiche per un piano tariffario regolabile nell'interfaccia utente:

  1. Accedi alla finestra di dialogo Notifiche.
  2. Fai clic su +Avvisa nella colonna Azioni per il piano tariffario.
  3. Fai clic su Modifica.
  4. Modifica i valori in base alle necessità.
  5. Fai clic su Salva notifica.

Eliminare le notifiche per un piano tariffario regolabile utilizzando l'interfaccia utente

Per eliminare una condizione e un'azione di notifica:

  1. Accedi alla finestra di dialogo Notifiche.
  2. Fai clic su +Notifica nella colonna Azioni per il piano tariffario.
  3. Fai clic su Elimina notifica.

Configurazione delle notifiche per un piano tariffario regolabile utilizzando l'API

Per configurare una notifica per un piano tariffario variabile utilizzando l'API, segui la procedura descritta in Gestire condizioni e azioni di notifica utilizzando l'API e utilizza gli attributi descritti in questa sezione.

Per configurare la condizione di notifica (notificationCondition), utilizza i seguenti valori dell'attributo. Per ulteriori informazioni, consulta le proprietà di configurazione per le condizioni di notifica.

Attributo Valore
RATEPLAN ID del piano tariffario regolabile delle notifiche.
PUBLISHED TRUE per indicare che il piano di frequenza delle notifiche regolabile deve essere pubblicato.
UsageTarget Percentuale del numero target di transazioni al momento in cui vuoi attivare una notifica.

Questo attributo ti consente di inviare una notifica agli sviluppatori quando stanno per raggiungere o hanno raggiunto il numero di transazioni target per un piano tariffario delle notifiche regolabile che hanno acquistato. Ad esempio, se uno sviluppatore ha acquistato un piano tariffario per le notifiche regolabile e il numero di transazioni target per lo sviluppatore è stato impostato su 1000, puoi inviare una notifica quando raggiunge 800 transazioni (80% del numero di transazioni target), 1000 transazioni (100%) o 1500 transazioni (150%).

  • Per impostare una percentuale esatta, inserisci %= n. Ad esempio, %= 80 invierà notifiche quando la percentuale del numero di transazioni di destinazione raggiunge l'80%.
  • Per impostare un intervallo percentuale, inserisci le percentuali di inizio e fine e il valore di incremento come segue: %= start to end by n. Ad esempio, un valore di %= 80 to 100 by 10 invierà notifiche quando la percentuale del numero target di transazioni raggiunge l'80%, il 90% e il 100%.

Per configurare l'azione di notifica, in actions imposta i seguenti valori. Per maggiori informazioni, consulta Proprietà di configurazione per le azioni di notifica.

Attributo Valore
actionAttribute WEBHOOK per attivare un webhook.
value ID del webhook che hai definito nella sezione precedente, Creazione di webhook utilizzando l'API.

Di seguito è riportato un esempio di come creare una condizione di notifica che attiva un webhook quando la percentuale del numero target di transazioni raggiunge l'80%, il 90%, il 100%, il 110% e il 120%.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

Per informazioni su come visualizzare, aggiornare ed eliminare una condizione e un'azione di notifica, consulta:

Codici di risposta webhook

Di seguito sono riportati i codici di risposta dei webhook e la relativa interpretazione da parte del sistema.

Codice di risposta Descrizione
2xx Operazione riuscita
5xx

Richiesta non riuscita. Il sistema riproverà la richiesta fino a tre volte a intervalli di 5 minuti.

Nota: i timeout di lettura e connessione per le richieste webhook sono di 3 secondi ciascuno, il che può comportare richieste non riuscite.
Other response Richiesta non riuscita. Il sistema non proverà nuovamente a inviare la richiesta.