Configurare le notifiche utilizzando i webhook

Stai visualizzando la documentazione di Apigee Edge.
Consulta la documentazione di Apigee X. info

Che cos'è un webhook?

Un webhook definisce un gestore 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 di monetizzazione, 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 gestione di Edge o l'API di gestione e monetizzazione:

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

Gestire i webhook

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

Gestire i 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.

Esplorare la pagina Webhook

Accedi alla pagina Webhook, come descritto di seguito.

Edge

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

Classic Edge (Private Cloud)

Per accedere alla pagina Webhook utilizzando l'interfaccia utente di Classic 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 Amministratore > Webhook.

Viene visualizzata la pagina Webhook.

La pagina Webhook ti consente di:

Aggiungere 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 callback che verrà chiamato quando viene attivata la notifica di un evento. Vedi Configurare il gestore callback.
  4. Fai clic su Salva.

Il webhook viene aggiunto all'elenco ed è abilitato 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 sul webhook che vuoi modificare e fai clic su nel menu delle azioni.
  3. Modifica i campi del webhook in base alle esigenze.
  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.

Eliminare 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 che vuoi 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.

Visualizzare 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"
    }

  ]
}

Visualizzare un webhook utilizzando la 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"
 }

Aggiungere 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 callback che verrà chiamato quando viene attivata la notifica di un evento.

Ad esempio, il seguente comando 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"
}

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 comando aggiorna il gestore 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 è 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"
}

Attivare o disattivare un webhook utilizzando l'API

Attiva o disattiva un webhook inviando una richiesta POST a /mint/organizations/{org_name}/webhooks/{webhook_id}, come hai fatto quando hai aggiornato 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, il seguente comando 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"
}

Eliminare 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, il seguente comando 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

Configurare il gestore callback

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

Configurare le 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.

Accedere 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 l'interfaccia utente di Edge:

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

    Viene visualizzata la finestra di dialogo Notifiche.

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

Classic Edge (Private Cloud)

Per accedere alla pagina Notifiche:

  1. Crea un piano tariffario 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.

Aggiungere notifiche per un piano tariffario regolabile utilizzando l'interfaccia utente

Per aggiungere notifiche per un piano tariffario regolabile utilizzando l'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 target in cui vuoi che venga attivata una notifica. In particolare:
    • Per impostare una percentuale esatta, inserisci la percentuale nel campo Al/Dal % e lascia vuoto il campo Al %.
    • Per impostare un intervallo di percentuali, inserisci la percentuale iniziale e finale rispettivamente nei campi Al/Dal % e Al % e un valore di incremento nel campo Passo %. Per impostazione predefinita, le notifiche vengono inviate con incrementi del 10% all'interno dell'intervallo specificato.

    Il campo Notify At viene aggiornato in modo da riflettere ogni percentuale del numero di transazioni target 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 delle 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 utilizzando l'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 esigenze.
  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.

Configurare le 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 saperne di più, consulta Proprietà di configurazione per le condizioni di notifica.

Attributo Valore
RATEPLAN ID del piano tariffario di notifica regolabile.
PUBLISHED TRUE per indicare che il piano tariffario 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 si avvicinano o hanno raggiunto il numero di transazioni target 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 di transazioni target per lo sviluppatore è stato impostato su 1000, puoi inviargli una notifica quando ha raggiunto 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 target raggiunge l'80%.
  • Per impostare un intervallo di percentuali, inserisci le percentuali iniziale e finale e il valore di incremento nel seguente modo: %= start to end by n. Ad esempio, un valore di %= 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, imposta i seguenti valori in actions. Per saperne di più, 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, Creare 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 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, vedi:

Codici di risposta webhook

Di seguito è riportato un riepilogo dei codici di risposta webhook e di come vengono interpretati dal sistema.

Codice di risposta Descrizione
2xx Operazione riuscita
5xx

Richiesta non riuscita. Il sistema ritenterà 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 ritenterà la richiesta.