Configurare le notifiche utilizzando i webhook

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

Che cos'è un webhook?

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

Per configurare le notifiche utilizzando i webhook, completa i passaggi seguenti utilizzando l'interfaccia utente di gestione perimetrale o l'API di gestione e monetizzazione:

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

Gestione dei webhook

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

Gestire i webhook utilizzando l'interfaccia utente

Aggiungi e gestisci i webhook che definiscono i gestori dei callback per gli eventi di notifica utilizzando la UI, come descritto nelle sezioni seguenti.

Esplorazione della pagina webhook

Accedi alla pagina webhook, come descritto di seguito.

Perimetrale

Per accedere alla pagina webhook utilizzando l'interfaccia utente 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 consente di:

Classic Edge (private cloud)

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

  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 di callback che verrà chiamato quando viene attivata la notifica dell'evento. Vedi Configurazione del gestore callback.
  4. Fai clic su Salva.

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

Modifica di un webhook utilizzando l'interfaccia utente

Per modificare un webhook utilizzando l'interfaccia utente:

  1. Accedi alla pagina webhook.
  2. Posiziona il cursore sul webhook da modificare e fai clic su nel menu Azioni.
  3. Modifica i campi del webhook come richiesto.
  4. Fai clic su Aggiorna webhook.

Attivare o disattivare un webhook utilizzando l'interfaccia utente

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

  1. Accedi alla pagina webhook.
  2. Posiziona il cursore sul webhook e attiva o 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 sul webhook da eliminare e fai clic su .

Il webhook viene eliminato e rimosso dall'elenco.

Gestire i webhook utilizzando l'API

Aggiungi e gestisci i 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 utilizzando 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 della 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 utilizzando l'API

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

Ad esempio, quanto segue crea 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 è riportato 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"
}

Modifica di un webhook utilizzando l'API

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

Ad esempio, quanto segue aggiorna il gestore di callback associato a webhook1:

curl -X POST "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 è riportato 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 utilizzando l'API

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

Ad esempio, quanto segue attiva 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 è riportato 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 del 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 callback

Di seguito è riportato il formato della richiesta JSON inviata al gestore di callback definito da un webhook quando viene attivata una notifica di evento. Devi assicurarti che il gestore di 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 modificabile

Configura le notifiche utilizzando i webhook per un piano tariffario modificabile utilizzando l'UI o l'API.

Impostazione delle notifiche per un piano tariffario modificabile tramite l'interfaccia utente

Imposta le notifiche utilizzando i webhook per un piano tariffario modificabile utilizzando l'interfaccia utente, come descritto di seguito.

Accedere alla finestra di dialogo Notifiche per un piano tariffario modificabile

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

Perimetrale

Per accedere alla finestra di dialogo delle notifiche utilizzando l'interfaccia utente Edge:

  1. Crea e pubblica un piano con frequenza di notifica regolabile, come descritto in Specificare i dettagli del piano di notifica modificabile.
  2. Accedi alla pagina Piani tariffari selezionando Pubblica > Monetizzazione > Piani tariffari nella barra di navigazione a sinistra.
  3. Posiziona il cursore sul piano del tasso di notifica regolabile pubblicato per visualizzare le azioni.
  4. Fai clic su +Notifica.

    Viene visualizzata la finestra di dialogo Notifiche.

    Nota: per poter visualizzare l'azione +Notifica, il piano tariffario deve essere pubblicato.

Classic Edge (private cloud)

Per accedere alla pagina Notifiche:

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

    Viene visualizzata la finestra di dialogo Notifiche.

Aggiunta di notifiche per un piano tariffario variabile mediante l'interfaccia utente

Per aggiungere notifiche per un piano tariffario modificabile 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 target di transazioni in cui vuoi che venga attivata la notifica. Nello specifico:
    • Per impostare una percentuale esatta, inserisci la percentuale nel campo At/Da % e lascia vuoto il campo A %.
    • Per impostare un intervallo percentuale, inserisci rispettivamente la percentuale di inizio e di fine nei campi A/Da % e A % e un valore di incremento nel campo %passaggio. Per impostazione predefinita, le notifiche vengono inviate con incrementi del 10% entro l'intervallo specificato.

    Il campo Notify At viene aggiornato per riflettere ogni percentuale del numero target di transazioni 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.

Modifica delle notifiche per un piano tariffario regolabile mediante 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 +Notifica nella colonna Azioni per il piano tariffario.
  3. Fai clic su Modifica.
  4. Modifica i valori come richiesto.
  5. Fai clic su Salva notifica.

Eliminazione delle notifiche per un piano tariffario modificabile tramite 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 modificabile utilizzando l'API

Per configurare una notifica per un piano tariffario regolabile utilizzando l'API, utilizza la procedura descritta in Gestire le condizioni e le 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 degli attributi. Per maggiori informazioni, consulta la sezione Proprietà di configurazione per le condizioni di notifica.

Attributo Valore
RATEPLAN ID del piano del tasso di notifica modificabile.
PUBLISHED TRUE per indicare che il piano del tasso di notifica regolabile deve essere pubblicato.
UsageTarget Percentuale del numero di transazioni target in cui vuoi che venga attivata una notifica.

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

  • Per impostare una percentuale esatta, inserisci %= n. Ad esempio, %= 80 invia notifiche quando la percentuale del numero target di transazioni raggiunge l'80%.
  • Per impostare un intervallo percentuale, inserisci le percentuali di inizio e fine e il valore in base al quale incrementare come segue: %= start to end by n. Ad esempio, il valore %= 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 la sezione Proprietà di configurazione per le azioni di notifica.

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

Di seguito è riportato un esempio di come creare una condizione di notifica che attivi 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 riepilogati i codici di risposta dei webhook e il modo in cui vengono interpretati dal 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 di 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 riproverà la richiesta.