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. In alternativa all'utilizzo dei modelli di notifica sulla monetizzazione, puoi creare webhook e configurarli per gestire le 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 di 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 di callback per gli eventi di notifica utilizzando l'interfaccia utente o l'API.

Gestione dei webhook utilizzando l'interfaccia utente

Aggiungi e gestisci i webhook che definiscono i gestori di 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'UI di Edge:

  1. Accedi a 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:

Perimetrale classico (Private Cloud)

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

  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 Amministratore > 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. Consulta Configurazione del gestore di callback.
  4. Fai clic su Salva.

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

Modifica di un webhook tramite la UI

Per modificare un webhook utilizzando l'interfaccia utente:

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

Attivazione o disattivazione di 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'UI:

  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.

Gestione dei webhook mediante l'API

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

Visualizzazione di tutti i webhook utilizzando l'API

Per visualizzare tutti i webhook, invia 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 viene 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

Per visualizzare un singolo webhook, invia 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 viene fornito 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 trasmettere 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 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"
}

Modifica di un webhook utilizzando l'API

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

Ad esempio, di seguito viene aggiornato il gestore di 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 utilizzando l'API

Abilita o disabilita un webhook inviando una richiesta POST a /mint/organizations/{org_name}/webhooks/{webhook_id}, come hai fatto durante l'aggiornamento di un webhook, e imposta l'attributo abilitato nel corpo della richiesta su true o false, rispettivamente. Se disabiliti 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 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 di 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 regolabile

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

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

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

Accedi alla finestra di dialogo Notifiche per un piano tariffario regolabile

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

Edge

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

  1. Crea e pubblica un piano tariffario di notifica regolabile, come descritto in Specificare i dettagli del piano di notifica regolabile.
  2. Per accedere alla pagina Piani tariffari, seleziona 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 +Invia notifica.

    Viene visualizzata la finestra di dialogo Notifiche.

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

Perimetrale classico (Private Cloud)

Per accedere alla pagina Notifiche:

  1. Crea un piano di 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 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 At/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 per riflettere ogni percentuale del numero di transazioni target che attiverà un evento.

  3. Per impostare altre condizioni di notifica, 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 relative a un piano tariffario regolabile, vai all'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 in base alle necessità.
  5. Fai clic su Save Notification (Salva notifica).

Eliminazione delle 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 regolabile utilizzando l'API, segui 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 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 con il tasso di notifica regolabile deve essere pubblicato.
UsageTarget Percentuale del numero di transazioni target in corrispondenza del momento in cui vuoi che venga attivata una notifica.

Questo attributo ti consente di informare gli 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 lui è stato impostato su 1000, puoi avvisarlo quando ha raggiunto 800 transazioni (80% del numero target di transazioni), 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 target 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 %= 80 to 100 by 10 invierà notifiche quando la percentuale del numero di transazioni target 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 attivi un webhook quando la percentuale del numero di transazioni target 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 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 : il timeout di lettura e di connessione per le richieste webhook è di 3 secondi ciascuno, e ciò può comportare richieste non riuscite.
Other response Richiesta non riuscita. Il sistema non proverà nuovamente a inviare la richiesta.