Pubblica le API utilizzando l'API Edge

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

Questa sezione descrive come utilizzare l'API Edge per creare prodotti API da pubblicare nei portali per sviluppatori.

Creare prodotti API utilizzando l'API

I prodotti API consentono agli sviluppatori di registrare le app che utilizzano le API tramite chiavi API e token di accesso OAuth. I prodotti API sono progettati per consentirti di "raggruppare" le risorse API e poi pubblicare questi bundle su diversi gruppi di sviluppatori. Ad esempio, potresti dover pubblicare un insieme di risorse API per gli sviluppatori partner e un altro bundle per gli sviluppatori esterni. I prodotti API ti consentono di eseguire questo bundling in tempo reale, senza richiedere modifiche alle API stesse. Un ulteriore vantaggio è che l'accesso degli sviluppatori può essere "aggiornato" e "declassato" senza che gli sviluppatori debbano ottenere nuove chiavi utente per le loro app.

Per creare un prodotto API utilizzando l'API, invia una richiesta POST a /organizations/{org_name}/apiproducts. Per saperne di più, consulta il riferimento API Crea prodotto API.

La seguente richiesta crea un prodotto API denominato weather_free. Il prodotto API fornisce l'accesso a tutte le API esposte dal proxy API denominato weatherapi di cui è stato eseguito il deployment nell'ambiente test. Il tipo di approvazione è impostato su auto, il che indica che qualsiasi richiesta di accesso verrà approvata.

curl -X POST https://api.enterprise.apigee.com/v1/organization/myorg/apiproducts \
-H "Content-Type:application/json" \
-d \
'{
  "approvalType": "auto",
  "displayName": "Free API Product",
  "name": "weather_free",
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ]
}' \
-u email:password

Esempio di risposta:

{
  "apiResources" : [ ],
  "approvalType" : "auto",
  "attributes" : [ ],
  "createdAt" : 1362759663145,
  "createdBy" : "developer@apigee.com",
  "displayName" : "Free API Product",
  "environments" : [ "test" ],
  "lastModifiedAt" : 1362759663145,
  "lastModifiedBy" : "developer@apigee.com",
  "name" : "weather_free",
  "proxies" : [ "weatherapi" ],
  "scopes" : [ ]
}

Il prodotto API creato sopra implementa lo scenario più semplice, autorizzando le richieste a un proxy API in un ambiente. Definisce un prodotto API che consente a un'app autorizzata di accedere a qualsiasi risorsa API a cui si accede tramite il proxy API in esecuzione nell'ambiente di test. I prodotti API espongono impostazioni di configurazione aggiuntive che consentono di personalizzare il controllo dell'accesso alle API per diversi gruppi di sviluppatori. Ad esempio, puoi creare due prodotti API che forniscono l'accesso a proxy API diversi. Puoi anche creare due prodotti API che forniscono l'accesso agli stessi proxy API, ma con impostazioni di quota associate diverse.

Impostazioni di configurazione del prodotto API

I prodotti API espongono le seguenti opzioni di configurazione:

Nome Descrizione Predefinito Obbligatorio?
apiResources

Un elenco separato da virgole di URI o percorsi delle risorse, "raggruppati" nel prodotto API.

Per impostazione predefinita, i percorsi delle risorse vengono mappati dalla proxy.pathsuffix variabile. Il suffisso del percorso del proxy è definito come il frammento URI che segue il percorso di base ProxyEndpoint. Ad esempio, nel prodotto API di esempio riportato di seguito, l'elemento apiResources è definito come /forecastrss. Poiché il percorso di base definito per questo proxy API è /weather, significa che questo prodotto API consente solo le richieste a /weather/forecastrss.

Puoi selezionare un percorso specifico o tutti i sottopercorsi con un carattere jolly. I caratteri jolly (/** e /*) sono supportati. Il carattere jolly con doppio asterisco indica che sono inclusi tutti i sub-URI. Un singolo asterisco indica che sono inclusi solo gli URI di un livello inferiore. inclusi.

Per impostazione predefinita, '/' supporta le stesse risorse di '/**', nonché il percorso di base definito dal proxy API. Ad esempio, se il percorso di base del proxy API è /v1/weatherapikey, il prodotto API supporta le richieste a /v1/weatherapikey e a qualsiasi sotto-URI, ad esempio /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA e così via. Per informazioni su come modificare il comportamento di questa impostazione predefinita, consulta Gestire i prodotti API.

 N/D No
approvalType Specifica come vengono approvate le chiavi API per accedere alle API definite dal prodotto API. Se impostata su manual, la chiave generata per l'app è nello stato "In attesa". Queste chiavi non funzioneranno finché non saranno state approvate esplicitamente. Se impostata su auto, tutte le chiavi vengono generate nello stato "Approvato" e funzionano immediatamente. (auto viene in genere utilizzato per fornire l'accesso a prodotti API senza costi/di prova che forniscono quote o funzionalità limitate.) N/D Sì
attributes

Array di attributi che possono essere utilizzati per estendere il profilo del prodotto API predefinito con metadati specifici del cliente.

Utilizza questa proprietà per specificare il livello di accesso del prodotto API come pubblico, privato o interno. Ad esempio:
"attributes": [
{
"name": "access",
"value": "public"
},
{
"name": "foo",
"value": "foo"
},
{
"name": "bar",
"value": "bar"
}
]
N/D No
scopes Un elenco separato da virgole di ambiti OAuth convalidati in fase di runtime. (Apigee Edge convalida che gli ambiti in qualsiasi token di accesso presentato corrispondano all'ambito impostato nel prodotto API.) N/D No
proxies Proxy API denominati a cui è associato questo prodotto API. Specificando i proxy, puoi associare le risorse del prodotto API a proxy API specifici, impedendo agli sviluppatori di accedere a queste risorse tramite altri proxy API. N/D No. Se non è definito, apiResources deve essere definito in modo esplicito (vedi le informazioni per apiResources sopra) e la variabile flow.resource.name deve essere impostata nella policy AssignMessage.
environments Ambienti denominati (ad esempio "test" o "prod") a cui è associato questo prodotto API. Specificando uno o più ambienti, puoi associare le risorse elencate nel prodotto API a un ambiente specifico, impedendo agli sviluppatori di accedere a queste risorse tramite proxy API in un altro ambiente. Questa impostazione viene utilizzata, ad esempio, per impedire l'accesso alle risorse associate ai proxy API in "prod" da parte dei proxy API di cui è stato eseguito il deployment in "test". N/D No. Se non è definito, apiResources deve essere definito in modo esplicito e la variabile flow.resource.name deve essere impostata nella policy AssignMessage.
quota Numero di richieste consentite per app nell'intervallo di tempo specificato. N/D No
quotaInterval Numero di unità di tempo su cui vengono valutate le quote N/D No
quotaTimeUnit L'unità di tempo (minuto, ora, giorno o mese) su cui vengono conteggiate le quote. N/D No

Di seguito è riportato un esempio più dettagliato per la creazione di un prodotto API. 

curl -X POST  https://api.enterprise.apigee.com/v1/o/{org_name}/apiproducts \
-H "Content-Type:application/json" -d \
'{
  "apiResources": [ "/forecastrss" ],
  "approvalType": "auto", 
  "attributes":
    [ {"name": "access", "value": "public"} ],
  "description": "Free API Product",
  "displayName": "Free API Product",
  "name": "weather_free",
  "scopes": [],
  "proxies": [ "weatherapi" ],
  "environments": [ "test" ],
  "quota": "10",
  "quotaInterval": "2",
  "quotaTimeUnit": "hour" }' \
-u email:password

Esempio di risposta

{
  "apiResources" : [ "/forecastrss" ],
  "approvalType" : "auto",
  "attributes" : [ {
    "name" : "access",
    "value" : "public"
  },
  "createdAt" : 1344454200828,
  "createdBy" : "admin@apigee.com",
  "description" : "Free API Product",
  "displayName" : "Free API Product",
  "lastModifiedAt" : 1344454200828,
  "lastModifiedBy" : "admin@apigee.com",
  "name" : "weather_free",
  "scopes" : [ ],
  "proxies": [ {'weatherapi'} ],
  "environments": [ {'test'} ],
  "quota": "10",
  "quotaInterval": "1",
  "quotaTimeUnit": "hour"}'
}

Informazioni sugli ambiti

Un ambito è un concetto tratto da OAuth e corrisponde approssimativamente al concetto di "autorizzazione". Su Apigee Edge, gli ambiti sono completamente facoltativi. Puoi utilizzare gli ambiti per ottenere un'autorizzazione più granulare. Ogni chiave utente rilasciata a un'app è associata a un "ambito principale". L' ambito principale è l'insieme di tutti gli ambiti di tutti i prodotti API per cui l'app è stata approvata. Per le app approvate per il consumo di più prodotti API, l'ambito principale è l'unione di tutti gli ambiti definiti nei prodotti API per cui la chiave utente è stata approvata.

Visualizzare i prodotti API

Per visualizzare i prodotti API creati per un'organizzazione utilizzando l'API, consulta le seguenti sezioni:

Di seguito è riportato un esempio di come visualizzare i prodotti API utilizzando l'API:

curl -X GET "https://ext.apiexchange.org/v1/mint/organizations/{org_name}/products?monetized=true" \
  -H "Accept:application/json" \
  -u email:password

La risposta dovrebbe essere simile alla seguente (viene mostrata solo una parte della risposta):

{
  "product" : [ {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "payment api product",
    "displayName" : "payment",
    "id" : "payment",
    "name" : "payment",
    "organization" : {
      ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  }, {
    "customAtt1Name" : "user",
    "customAtt2Name" : "response size",
    "customAtt3Name" : "content-length",
    "description" : "messaging api product",
    "displayName" : "messaging",
    "id" : "messaging",
    "name" : "messaging",
    "organization" : ...
    },
    "pricePoints" : [ ],
    "status" : "CREATED",
    "transactionSuccessCriteria" : "status == 'SUCCESS'"
  } ],
  "totalRecords" : 2
}

Registrare gli sviluppatori utilizzando l'API

Tutte le app appartengono a sviluppatori o aziende. Pertanto, per creare un'app, devi prima registrare uno sviluppatore o un'azienda.

Gli sviluppatori vengono registrati in un'organizzazione creando un profilo. Tieni presente che l'indirizzo email dello sviluppatore incluso nel profilo viene utilizzato come chiave univoca per lo sviluppatore in Apigee Edge.

Per supportare la monetizzazione, devi definire gli attributi di monetizzazione quando crei o modifichi gli sviluppatori. Puoi anche definire altri attributi arbitrari da utilizzare in analisi personalizzate, applicazione di policy personalizzate e così via. Questi attributi arbitrari non verranno interpretati da Apigee Edge,

Ad esempio, la seguente richiesta registra un profilo per uno sviluppatore il cui indirizzo email è ntesla@theremin.com e definisce un sottoinsieme di attributi di monetizzazione utilizzando l'API Crea sviluppatore:

$ curl -H "Content-type:application/json" -X POST -d \
'{"email" : "ntesla@theremin.com", 
  "firstName" : "Nikola", 
  "lastName" : "Tesla", 
  "userName" : "theremin", 
  "attributes" : [ 
  { 
    "name" : "project_type", 
    "value" : "public"
  },
  {    
   "name": "MINT_BILLING_TYPE",
   "value": "POSTPAID"
  },
  {
   "name": "MINT_DEVELOPER_ADDRESS",
   "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
  },
  {
   "name": "MINT_DEVELOPER_TYPE",
   "value": "TRUSTED"
  },
  {    
   "name": "MINT_HAS_SELF_BILLING,
   "value": "FALSE"
  },
  {
   "name" : "MINT_SUPPORTED_CURRENCY",
   "value" : "usd"
  }
 ] 
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers \
-u email:password

Esempio di risposta

{
          "email" : "ntesla@theremin.com",
          "firstName" : "Nikola",
          "lastName" : "Tesla",
          "userName" : "theremin",
          "organizationName" : "{org_name}",
          "status" : "active",
          "attributes" : [ 
          {
            "name" : "project_type",
            "value" : "public"
          },
          {    
             "name": "MINT_BILLING_TYPE",
             "value": "POSTPAID"
          },
          {
             "name": "MINT_DEVELOPER_ADDRESS",
             "value": "{\"address1\":\"Dev One Address\",\"city\":\"Pleasanton\",\"country\":\"US\",\"isPrimary\":true,\"state\":\"CA\",\"zip\":\"94588\"}"
          },
          {
             "name": "MINT_DEVELOPER_TYPE",
             "value": "TRUSTED"
          },
          {    
             "name": "MINT_HAS_SELF_BILLING,
             "value": "FALSE"
          },
          {
             "name" : "MINT_SUPPORTED_CURRENCY",
             "value" : "usd"
          } 
          ],
          "createdAt" : 1343189787717,
          "createdBy" : "admin@apigee.com",
          "lastModifiedAt" : 1343189787717,
          "lastModifiedBy" : "admin@apigee.com"
        }

Registrare le app per sviluppatori utilizzando l'API

Ogni app registrata su Apigee Edge è associata a uno sviluppatore e a un prodotto API. Quando un'app viene registrata per conto di uno sviluppatore, Apigee Edge genera una "credenziale" (una coppia di chiave utente e secret) che identifica l'app. L'app deve quindi trasmettere queste credenziali come parte di ogni richiesta a un prodotto API associato all'app.

La seguente richiesta utilizza l'API Crea app per sviluppatori per registrare un'app per lo sviluppatore creato sopra: ntesla@theremin.com. Quando registri un'app, definisci un nome per l'app, un callbackUrl e un elenco di uno o più prodotti API: 
$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "weather_free"], 
  "callbackUrl" : "login.weatherapp.com", 
  "keyExpiresIn" : "2630000000",
  "name" : "weatherapp"}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps \
-u email:password

Il callbackUrl viene utilizzato da alcuni tipi di autorizzazione con OAuth (ad esempio il codice di autorizzazione) per convalidare le richieste di reindirizzamento dall'app. Se utilizzi OAuth, questo valore deve essere impostato sullo stesso valore di redirect_uri utilizzato per effettuare richieste OAuth.

L'attributo keyExpiresIn specifica, in millisecondi, la durata della chiave utente che verrà generata per l'app per sviluppatori. Il valore predefinito, -1, indica un periodo di validità infinito.

Esempio di risposta

{
  "appId": "5760d130-528f-4388-8c6f-65a6b3042bd1",
  "attributes": [
    {
      "name": "DisplayName",
      "value": "Test Key Expires"
    },
    {
      "name": "Notes",
      "value": "Just testing this attribute"
    }
  ],
  "createdAt": 1421770824390,
  "createdBy": "wwitman@apigee.com",
  "credentials": [
    {
      "apiProducts": [
        {
          "apiproduct": "ProductNoResources",
          "status": "approved"
        }
      ],
      "attributes": [],
      "consumerKey": "jcAFDcfwImkJ19A5gTsZRzfBItlqohBt",
      "consumerSecret": "AX7lGGIRJs6s8J8y",
      "expiresAt": 1424400824401,
      "issuedAt": 1421770824401,
      "scopes": [],
      "status": "approved"
    }
  ],
  "developerId": "e4Oy8ddTo3p1BFhs",
  "lastModifiedAt": 1421770824390,
  "lastModifiedBy": "wwitman@apigee.com",
  "name": "TestKeyExpires",
  "scopes": [],
  "status": "approved"
}

Gestire le chiavi utente per le app utilizzando l'API

Recuperare la chiave utente (la chiave API) per l'app

Le credenziali di un'app (prodotto API, chiave utente e secret) vengono restituite come parte del profilo dell'app. Un amministratore di un'organizzazione può recuperare la chiave utente in qualsiasi momento.

Il profilo dell'app mostra il valore della chiave utente e del secret, lo stato della chiave utente e le eventuali associazioni di prodotti API per la chiave. In qualità di amministratore, puoi recuperare il profilo della chiave utente in qualsiasi momento utilizzando l'API Recupera dettagli chiave per un'app per sviluppatori:

$ curl -X GET -H "Accept: application/json" \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password

Esempio di risposta

{
  "apiProducts" : [ {
    "apiproduct" : "weather_free",
    "status" : "approved"
  } ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Per saperne di più, consulta Recupera dettagli chiave per un'app per sviluppatori.

Aggiungere un prodotto API a un app e a una chiave

Per aggiornare un'app in modo da aggiungere un nuovo prodotto API, devi aggiungere il prodotto API alla chiave dell'app utilizzando l'API Aggiungi prodotto API alla chiave. Per saperne di più, consulta Aggiungi prodotto API alla chiave.

L'aggiunta di un prodotto API a una chiave dell'app consente all'app che contiene la chiave di accedere alle risorse API raggruppate nel prodotto API. La seguente chiamata al metodo aggiunge un nuovo prodotto API a un app:

$ curl -H "Content-type:application/json" -X POST -d \
'{
  "apiProducts": [ "newAPIProduct"]
}' \
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J \
-u email:password

Esempio di risposta:

{
  "apiProducts": [
   {
     "apiproduct": "weather_free",
     "status": "approved"
   },
   {
     "apiproduct": "newAPIProduct",
     "status": "approved"
   }
 ],
 "attributes": [],
 "consumerKey": "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
 "consumerSecret": "1eluIIdWG3JGDjE0",
 "expiresAt": -1,
 "issuedAt": 1411491156464,
 "scopes": [],
 "status": "approved"
 }

Approvare le chiavi utente

L'impostazione del tipo di approvazione su manuale consente di controllare quali sviluppatori possono accedere alle risorse protette dai prodotti API. Quando i prodotti API hanno l'approvazione della chiave impostata su manual, le chiavi utente devono essere approvate esplicitamente. Le chiavi possono essere approvate esplicitamente utilizzando l'API Approva o revoca una chiave specifica di un'app per sviluppatori:

$ curl -X POST -H "Content-type:appilcation/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J?"action=approve" \
-u email:password

Esempio di risposta

{
  "apiProducts" : [ {
  "apiproduct" : "weather_free",
  "status" : "approved"
} ],
  "attributes" : [ ],
  "consumerKey" : "HQg0nCZ54adKobpqEJaE8FefGkdKFc2J",
  "consumerSecret" : "1eluIIdWG3JGDjE0",
  "status" : "approved"
}

Per saperne di più, consulta Approva o revoca una chiave specifica di un'app per sviluppatori.

Approvare i prodotti API per le chiavi utente

Anche l'associazione di un prodotto API a una chiave utente ha uno stato. Affinché l'accesso all'API vada a buon fine, la chiave utente deve essere approvata, e la chiave utente deve essere approvata per il prodotto API appropriato. L'associazione di una chiave utente a un prodotto API può essere approvata utilizzando l'API Approva o revoca un prodotto API per una chiave per un'app per sviluppatori:

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=approve" \
-u email:password

Questo comando cURL non restituisce una risposta. Per saperne di più, consulta Approva o revoca un prodotto API per una chiave per un'app per sviluppatori.

Revocare i prodotti API per le chiavi utente

Esistono molti motivi per cui potresti dover revocare l'associazione di una chiave utente a un prodotto API. Potresti dover rimuovere un prodotto API da una chiave utente a causa del mancato pagamento da parte del sviluppatore, di un periodo di prova scaduto o quando un'app viene promossa da un prodotto API a un altro.

Per revocare l'associazione di una chiave utente a un prodotto API, utilizza l'API Approva o revoca una chiave specifica di un'app per sviluppatori , utilizzando l'azione di revoca sulla chiave utente dell'app per sviluppatori:

$ curl -X POST -H "Content-type:application/octet-stream" \ 
https://api.enterprise.apigee.com/v1/o/{org_name}/developers/ntesla@theremin.com/apps/weatherapp/keys/HQg0nCZ54adKobpqEJaE8FefGkdKFc2J/apiproducts/weather_free?"action=revoke" \
-u email:password

Questo comando cURL non restituisce una risposta. Per saperne di più, consulta Approva o revoca una chiave specifica di un'app per sviluppatori.

Applicare le impostazioni del prodotto API

Affinché i prodotti API vengano applicati, è necessario associare al flusso del proxy API uno dei seguenti tipi di policy:

  • VerifyAPIKey: accetta un riferimento a una chiave API, verifica che rappresenti un'app valida e corrisponda al prodotto API. Per saperne di più, consulta la policy Verifica chiave API.
  • OAuthV1, operazione "VerifyAccessToken": verifica la firma, convalida un token di accesso OAuth 1.0a e una "chiave utente" e associa l'app al prodotto API. Per saperne di più, consulta la policy OAuth v1.0a.
  • OAuthV2, operazione "VerifyAccessToken": verifica che il token di accesso OAuth 2.0 sia valido, associa il token all'app, verifica che l'app sia valida e poi associa l'app a un prodotto API. Per saperne di più, consulta lahome page di OAuth.

Una volta configurate le policy e i prodotti API, Apigee Edge esegue la seguente procedura:

  1. Apigee Edge riceve una richiesta e la indirizza al proxy API appropriato.
  2. Viene eseguita una policy che verifica la chiave API o il token di accesso OAuth presentato dal client.
  3. Edge risolve la chiave API o il token di accesso in un profilo dell'app.
  4. Edge risolve l'elenco (se presente) dei prodotti API associati all'app.
  5. Il primo prodotto API corrispondente viene utilizzato per popolare le variabili Quota.
  6. Se nessun prodotto API corrisponde alla chiave API o al token di accesso, la richiesta viene rifiutata.
  7. Edge applica il controllo dell'accesso basato su URI (ambiente, proxy API e percorso URI) in base alle impostazioni del prodotto API, nonché alle impostazioni di quota.

Salvo quando diversamente specificato, i contenuti di questa pagina sono concessi in base alla licenza Creative Commons Attribution 4.0, mentre gli esempi di codice sono concessi in base alla licenza Apache 2.0. Per ulteriori dettagli, consulta le norme del sito di Google Developers. Java è un marchio registrato di Oracle e/o delle sue consociate.

Ultimo aggiornamento 2026-09-10 UTC.