Questa pagina è stata tradotta dall'API Cloud Translation.

Pubblica le API utilizzando l'API Edge

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

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

Creare prodotti API utilizzando l'API

I prodotti API consentono agli sviluppatori di registrare le app che utilizzano le API utilizzando chiavi API e token di accesso OAuth. I prodotti basati su API sono progettati per consentirti di "raggruppare" le risorse dell'API e pubblicare questi pacchetti per diversi gruppi di sviluppatori. Ad esempio, potresti dover pubblicare un set di risorse API per gli sviluppatori partner, mentre ne pubblichi un altro per gli sviluppatori esterni. I prodotti API consentono di eseguire il raggruppamento in tempo reale, senza dover modificare le API. Un ulteriore vantaggio è che è possibile eseguire l'upgrade e il downgrade dell'accesso degli sviluppatori senza che gli sviluppatori debbano 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 ulteriori informazioni, consulta la sezione relativa alla creazione di un prodotto API.

La seguente richiesta crea un prodotto API chiamato weather_free. Il prodotto API fornisce l'accesso a tutte le API esposte dal proxy API denominato weatherapi di cui viene eseguito il deployment nell'ambiente test. Il tipo di approvazione è impostato su auto, a indicare 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 in precedenza implementa lo scenario più di base, 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 accessibile 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 accesso a diversi proxy API. Puoi anche creare due prodotti API che forniscono accesso agli stessi proxy API, ma con impostazioni delle quote associate diverse.

Impostazioni di configurazione del prodotto API

I prodotti API espongono le seguenti opzioni di configurazione:

Nome	Descrizione	Predefinito	Campo obbligatorio?
`apiResources`	Un elenco separato da virgole di URI, o percorsi delle risorse, "in bundle" 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 ProxyEndpoint. Ad esempio, nel prodotto API di esempio riportato di seguito, l'elemento `apiResources` viene definito come `/forecastrss`. Poiché il percorso di base definito per questo proxy API è `/weather`, ciò significa che questo prodotto API consente solo le richieste a `/weather/forecastrss`. Puoi selezionare un percorso specifico o tutti i percorsi secondari con un carattere jolly. I caratteri jolly (/** e /) sono supportati. Il carattere jolly con doppio asterisco indica che sono inclusi tutti gli URI secondari. 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 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 URI secondario, come /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA e così via. Consulta Gestire i prodotti basati su API per informazioni su come modificare il comportamento di questa impostazione predefinita.	N/A	No
`approvalType`	Specifica in che modo le chiavi API vengono approvate per l'accesso alle API definite dal prodotto API. Se viene impostata su `manual`, la chiave generata per l'app si trova nello stato "In attesa". Queste chiavi non funzioneranno finché non saranno approvate esplicitamente. Se impostato su `auto`, tutte le chiavi vengono generate nello stato "approvato" e funzionano subito. (`auto` viene generalmente utilizzato per fornire accesso a prodotti API di prova senza costi che offrono quote o funzionalità limitate).	N/A	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": "accesso", "value": "pubblici" }, { "name": "foo", "value": "foo" }, { "name": "bar", "value": "bar" }	N/A	No
`scopes`	Un elenco separato da virgole di ambiti OAuth convalidati durante il runtime. Apigee Edge convalida che gli ambiti in qualsiasi token di accesso presentato corrispondano all'ambito impostato nel prodotto API.	N/A	No
`proxies`	Proxy API denominati a cui è associato questo prodotto API. Specificando i proxy, puoi associare le risorse nel prodotto API a proxy API specifici, impedendo agli sviluppatori di accedere alle risorse tramite altri proxy API.	N/A	No. Se non viene definita, è necessario definire esplicitamente `apiResources` (consulta le informazioni relative a `apiResources` riportate sopra) e la variabile `flow.resource.name` deve essere impostata nel criterio di AssegnaMessage.
`environments`	Ambienti con nome (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 allo sviluppatore 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/A	No. Se non viene definita, è necessario definire in modo esplicito `apiResources` e la variabile `flow.resource.name` deve essere impostata nel criterio AssegnaMessage.
`quota`	Numero di richieste consentite per app nell'intervallo di tempo specificato.	N/A	No
`quotaInterval`	Numero di unità di tempo durante le quali vengono valutate le quote	N/A	No
`quotaTimeUnit`	L'unità di tempo (minuto, ora, giorno o mese) su cui vengono conteggiate le quote.	N/A	No

Di seguito viene fornito 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 mappa 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 emessa a un'app è associata a un "ambito master". L'ambito master è 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 master è l'unione di tutti gli ambiti definiti nei prodotti API per i quali la chiave utente è stata approvata.

Visualizza i prodotti API

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

Visualizza prodotti API (monetizzata)
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 ricerca monetized su false. Ciò equivale a inviare una richiesta GET all'API dei prodotti dell'API List 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):

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

Registra gli sviluppatori utilizzando l'API

Tutte le app appartengono a sviluppatori o società. Di conseguenza, per creare un'app, devi prima registrare uno sviluppatore o una società.

Gli sviluppatori sono 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 tutto Apigee Edge.

Per supportare la monetizzazione, devi definire gli attributi per la monetizzazione durante la creazione o la modifica degli sviluppatori. Puoi anche definire altri attributi arbitrari da utilizzare nell'analisi personalizzata, nell'applicazione di criteri personalizzati e così via; questi attributi arbitrari non saranno 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 Create developer:

$ 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 degli 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 chiave e secret dell'utente) che identifica l'app. L'app deve quindi passare queste credenziali come parte di ogni richiesta a un prodotto API associato all'app.

La richiesta seguente utilizza l'API Create Developer App per registrare un'app per lo sviluppatore creato in precedenza: ntesla@theremin.com. Quando registri un'app, devi definire 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 è utilizzato da alcuni tipi di autorizzazione con OAuth (come 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à illimitata.

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 che utilizzano 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 come parte del profilo dell'app. L'amministratore di un'organizzazione può recuperare la chiave utente in qualsiasi momento.

Il profilo dell'app mostra il valore della chiave e del secret utente, lo stato della chiave utente ed eventuali associazioni di prodotti API per la chiave. In qualità di amministratore, puoi recuperare il profilo della chiave utente in qualsiasi momento utilizzando Recupera i dettagli chiave per un'API 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 la sezione Recupero dei dettagli chiave di un'app sviluppatore.

Aggiungi un prodotto API a un'app e una chiave

Per aggiornare un'app e aggiungere un nuovo prodotto API, devi aggiungere il prodotto API alla chiave dell'app utilizzando Aggiungi prodotto API all'API Key. Per saperne di più, consulta Aggiungere 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 integrate 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 manual consente di controllare quali sviluppatori possono accedere alle risorse protette dai prodotti API. Quando l'approvazione delle chiavi per i prodotti API è impostata su manual, le chiavi utente devono essere approvate esplicitamente. Le chiavi possono essere approvate esplicitamente utilizzando l'API Approva o Revoca la 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 la sezione Approvare o revocare la chiave specifica dell'app sviluppatore.

Approva prodotti API per le chiavi consumer

Anche l'associazione di un prodotto API con una chiave utente ha uno stato. Affinché l'accesso all'API abbia esito positivo, la chiave utente deve essere approvata e per il prodotto API appropriato. L'associazione di una chiave utente a un prodotto API può essere approvata utilizzando l'API Approva o Revoca prodotto API per una chiave per un'app sviluppatore:

$ 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 la sezione Approvare o revocare un prodotto API per una chiave per un'app sviluppatore.

Revoca prodotti API per le chiavi consumer

Esistono molti motivi per cui potrebbe essere necessario revocare l'associazione di una chiave utente con un prodotto API. Potrebbe essere necessario rimuovere un prodotto API da una chiave utente a causa del mancato pagamento da parte dello sviluppatore, di un periodo di prova scaduto o di un'app promossa da un prodotto API a un altro.

Per revocare l'associazione di una chiave utente con un prodotto API, utilizza l'API Approva o Revoca la chiave specifica dell'app per sviluppatori , utilizzando la revoca dell'azione in base alla chiave utente dell'app di sviluppo:

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

Applica le impostazioni del prodotto API

Per applicare l'applicazione forzata dei prodotti API, è necessario collegare uno dei seguenti tipi di criteri al flusso proxy API:

VerificationAPIKey: prende un riferimento a una chiave API, verifica che rappresenti un'app valida e corrisponde al prodotto API. Per saperne di più, consulta Verificare il criterio della 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ù, vedi Criterio OAuth v1.0a.
Operazione OAuthV2, "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 ulteriori informazioni, visita la home page OAuth.

Una volta configurati i criteri e i prodotti API, Apigee Edge esegue il seguente processo:

Una richiesta viene ricevuta da Apigee Edge e instradata al proxy API appropriato.
Viene eseguito un criterio 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) di 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 degli accessi basato su URI (ambiente, proxy API e percorso URI) in base alle impostazioni del prodotto API e alle impostazioni delle quote.