Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

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 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 in diversi gruppi di sviluppatori. Ad esempio, potresti dover pubblicare un insieme di risorse API per i tuoi sviluppatori partner, mentre pubblichi un altro bundle per gli sviluppatori esterni. I prodotti API ti consentono di eseguire questo raggruppamento al volo, senza richiedere modifiche alle API stesse. Un ulteriore vantaggio è che l'accesso sviluppatore può essere "aggiornato" e "declassato" senza richiedere agli sviluppatori di ottenere nuove chiavi consumer 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 chiamato weatherapi che è implementato 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 ti consentono di personalizzare il controllo dell'accesso alle tue 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 variabile `proxy.pathsuffix`. Il suffisso del percorso proxy è definito come il frammento URI che segue il percorso di base di 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 solo le richieste a `/weather/forecastrss` sono consentite da questo prodotto API. Puoi selezionare un percorso specifico oppure tutti i sottopercorsi con un carattere jolly. I caratteri jolly (/** e /) sono supportati. Il carattere jolly doppio asterisco indica che sono incluse tutte le URI secondarie. Un singolo asterisco indica che sono inclusi solo gli URI di un livello inferiore. Per impostazione predefinita, "/" supporta le stesse risorse di "/*" e il percorso base definito dal proxy API. Ad esempio, se il percorso base del proxy API è /v1/weatherapikey, allora il prodotto API supporta le richieste a /v1/weatherapikey e a qualsiasi URI secondario, ad esempio /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA e così via. Per informazioni sulla modifica del comportamento di questo valore predefinito, consulta la sezione Gestire i prodotti API.	N/D	No
`approvalType`	Specifica in che modo le chiavi API vengono approvate per accedere alle API definite dal prodotto API. Se impostato su `manual`, la chiave generata per l'app è nello stato "In attesa". Queste chiavi non funzioneranno finché non saranno state approvate esplicitamente. Se impostato su `auto`, tutte le chiavi vengono generate come "approvate" e funzionano immediatamente. (`auto` is typically used for providing access to free/trial API products that provide limited Quota or capabilities.)	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 verifica 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. Se specifichi i proxy, puoi associare le risorse nel 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 nel criterio AssignMessage.
`environments`	Ambienti denominati (ad esempio "test" o "prod") a cui è associato questo prodotto API. Se specifichi 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 i 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` 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) in 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 in tutti i prodotti API per cui l'app è stata approvata. Per le app approvate per l'utilizzo di più prodotti API, l'ambito principale è l'unione di tutti gli ambiti definiti nei prodotti API per i quali è stata approvata la chiave consumer.

Visualizza i prodotti API

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

Visualizza i prodotti API (monetizzati)
Per impostazione predefinita, vengono visualizzati solo i prodotti API monetizzati (ovvero i prodotti API con almeno un piano tariffario pubblicato). Per visualizzare tutti i prodotti API, imposta il parametro di query monetized su false. Ciò equivale a inviare una richiesta GET all'API List API products non monetizzata: https://api.enterprise.apigee.com/v1/organizations/{org_name}/apiproducts?expand=true
Visualizza prodotti API (non monetizzati)
Visualizzare i prodotti API idonei per uno sviluppatore
Visualizzare i prodotti API idonei per un'azienda

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 una società.

Gli sviluppatori vengono registrati in un'organizzazione creando un profilo. Tieni presente che l'email dello sviluppatore inclusa nel profilo viene utilizzata 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 norme 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 Create Developer App per registrare un'app per lo sviluppatore che hai 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

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 le richieste OAuth.

L'attributo keyExpiresIn specifica, in millisecondi, la durata della chiave utente che verrà generata per l'app dello sviluppatore. 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 consumer per le app utilizzando l'API

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

Le credenziali per un'app (prodotto API, chiave utente e secret) vengono restituite nell'ambito 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 Get Key Details for a Developer App:

$ 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 Recuperare i dettagli della 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 Add API Product to Key. Per saperne di più, consulta Aggiungi un 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 ti consente di controllare quali sviluppatori possono accedere alle risorse protette dai prodotti API. Quando l'approvazione delle chiavi dei prodotti API è impostata su manual, le chiavi consumer devono essere approvate esplicitamente. Le chiavi possono essere approvate esplicitamente utilizzando l'API Approva o revoca una chiave specifica dell'app sviluppatore:

$ 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 Approvare o revocare una chiave specifica dell'app dello sviluppatore.

Approvare i prodotti API per le chiavi consumer

Anche l'associazione di un prodotto API a una chiave utente ha uno stato. Perché l'accesso all'API vada a buon fine, la chiave utente deve essere approvata e 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 il 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 Approvare o revocare un prodotto API per una chiave per un'app per sviluppatori.

Revoca dei prodotti API per le chiavi consumer

Esistono molti motivi per cui potresti dover revocare l'associazione di una chiave consumer a un prodotto API. Potresti dover rimuovere un prodotto API da una chiave utente a causa del mancato pagamento da parte dello 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 chiave specifica dell'app per sviluppatori , utilizzando l'azione 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 Approvare o revocare una chiave specifica dell'app dello sviluppatore.

Applica le impostazioni del prodotto API

Affinché i prodotti API vengano applicati, al flusso del proxy API deve essere collegato 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 le norme sulla verifica della chiave API.
OAuthV1, operazione "VerifyAccessToken": verifica la firma, convalida un token di accesso OAuth 1.0a e la "chiave utente" e associa l'app al prodotto API. Il supporto di OAuth 1.0a è stato ritirato. Vedi Funzionalità ritirate.
OAuthV2, operazione "VerifyAccessToken": verifica che il token di accesso OAuth 2.0 sia valido, lo associa all'app, verifica che l'app sia valida e poi la associa a un prodotto API. Per saperne di più, consulta la home page di OAuth.

Una volta configurate le policy e i prodotti API, Apigee Edge esegue il seguente processo:

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