Pubblica le API utilizzando l'API Edge

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione 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 basati su API consentono agli sviluppatori di registrarsi le app che utilizzano API usando chiavi API e token di accesso OAuth. I prodotti basati su API sono progettati per consentono di "raggruppare" le risorse dell'API e quindi pubblicare questi pacchetti in diversi gruppi sviluppatori. Ad esempio, potresti dover pubblicare un set di risorse API per il tuo partner agli sviluppatori esterni, mentre pubblichi un altro bundle per sviluppatori esterni. I prodotti basati su API consentono di il raggruppamento in tempo reale, senza dover apportare modifiche alle API. Un Il vantaggio aggiuntivo è che è possibile eseguire l'upgrade dell'accesso sviluppatore e con "downgrade" senza richiedere agli sviluppatori di 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 ulteriori informazioni, consulta il riferimento API Create API Product.

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 è di cui è stato eseguito il deployment nell'ambiente test. Il tipo di approvazione è impostato su auto, a indicare che qualsiasi la 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ù basilare, autorizzando le richieste a un proxy API in un ambiente. Definisce un prodotto API che consente a un'app autorizzata di accedere Qualsiasi risorsa API a cui si accede tramite il proxy API in esecuzione nell'ambiente di test. Prodotti basati su API Esporre 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 allo stesso Proxy API, ma con impostazioni di quota diverse associate.

Impostazioni di configurazione del prodotto API

I prodotti API espongono le seguenti opzioni di configurazione:

Nome Descrizione Predefinito Obbligatorio?
apiResources

Un elenco di URI separati da virgole, o percorsi di risorse, "in bundle" nell'API prodotto.

Per impostazione predefinita, i percorsi delle risorse sono mappati dall'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 è definito come /forecastrss. Poiché il Il percorso di base definito per questo proxy API è /weather, il che significa che richieste a /weather/forecastrss sono consentite da questo prodotto API.

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 tutti sono inclusi gli URI secondari. Un singolo asterisco indica che solo gli URI di un livello inferiore sono inclusi.

Per impostazione predefinita, '/' supporta le stesse risorse di "/**" così come la base Percorso definito dal proxy API. Ad esempio, se il Percorso di base del proxy API è /v1/weatherapikey, quindi il prodotto API supporta richieste a /v1/weatherapikey e a qualsiasi URI secondari, ad esempio /v1/weatherapikey/forecastrss, /v1/weatherapikey/region/CA e così via. Consulta Gestisci i prodotti basati su API per informazioni sulla modifica del comportamento di questo valore predefinito.

 N/D No
approvalType Specifica in che modo le chiavi API vengono approvate per l'accesso alle API definite dal prodotto API. Se impostata su manual, la chiave generata per l'app è nello stato "In attesa" stato. Queste chiavi non funzioneranno finché non saranno state approvate esplicitamente. Se impostato su auto, tutte le chiavi vengono generate e lavorare subito. (auto corrisponde a tipicamente utilizzati per fornire l'accesso a prodotti API di prova/senza costi che offrono una quota limitata o capacità.) N/D Sì
attributes

Array di attributi che possono essere utilizzati per estendere il profilo del prodotto API predefinito con e 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": "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 nell'API product.) N/D No
proxies Proxy API con nome a cui è associato questo prodotto API. Specificando i proxy, puoi Associare risorse nel prodotto API a proxy API specifici, impedendo agli sviluppatori di accedere alle risorse mediante altri proxy API. N/D No. Se non viene specificato, apiResources deve essere definito esplicitamente (vedi le informazioni) per apiResources sopra) e la variabile flow.resource.name impostata in Assegna il criterio AskMessage.
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 allo sviluppatore di accedere a queste risorse tramite l'API. in un altro ambiente. Questa impostazione viene utilizzata, ad esempio, per impedire che le risorse associate ai proxy API in "prod" l'accesso da parte dei proxy API distribuiti "test". N/D No. Se non viene specificato, apiResources deve essere definito esplicitamente e Variabile flow.resource.name impostata nel criterioAssignMessage.
quota Numero di richieste consentite per app nell'intervallo di tempo specificato. N/D No
quotaInterval Numero di unità di tempo durante le quali 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 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 si riferisce approssimativamente al concetto di "autorizzazione". Attivato Apigee Edge, gli ambiti sono completamente facoltativi. Puoi utilizzare gli ambiti per ottenere dati autorizzazione. Ogni chiave consumer emessa per un'app è associata a un "ambito master". La l'ambito master è l'insieme di tutti gli ambiti in tutti i prodotti API per cui l'app è stata approvata. Per app approvate per il consumo di più prodotti API, l'ambito principale è l'unione di tutti gli ambiti definita 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 seguenti sezioni:

Di seguito viene fornito 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 avere un aspetto simile al seguente (è 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
}

Registra gli sviluppatori utilizzando l'API

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

Gli sviluppatori si registrano in un'organizzazione creando un profilo. Tieni presente che lo sviluppatore l'indirizzo email incluso nel profilo è usato come chiave univoca per lo sviluppatore in tutto Apigee Edge

Per supportare la monetizzazione, devi definire la monetizzazione attributi quando crei o modifichi gli sviluppatori. Puoi anche definire altre attributi per l'utilizzo in analisi personalizzate, applicazione di criteri personalizzati e così via; questi 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 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"
        }

Registrazione di app sviluppatore 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" (un chiave utente e coppia di dati segreti) che identifica l'app. L'app deve quindi passare queste credenziali nell'ambito di ogni richiesta a un prodotto API associato all'app.

La seguente richiesta utilizza il pulsante Crea API 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 una o più API prodotti: 
$ 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 è utilizzato da alcuni tipi di autorizzazione 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 utilizzate per le richieste OAuth.

L'attributo keyExpiresIn specifica, in millisecondi, la durata dell'evento chiave utente generata per l'app sviluppatore. Il valore predefinito, -1, indica un periodo di validità infinita.

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) dell'app

Le credenziali di un'app (prodotto API, chiave utente e segreto) vengono restituite nell'ambito della 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 e del segreto utente e lo stato del consumatore. e le eventuali associazioni di prodotti API per la chiave. In qualità di amministratore, puoi recuperare profilo chiave utente in qualsiasi momento utilizzando la funzionalità Recupera i dettagli chiave per un'app sviluppatore dell'API:

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

Vedi Per saperne di più, ottieni i dettagli chiave di un'app sviluppatore.

Aggiungi un prodotto API a un app e chiave

Per aggiornare un'app allo scopo di aggiungere un nuovo prodotto API, devi aggiungere il prodotto API alla chiave dell'app utilizzando l'API Add API Product to Key. Vedi Aggiungi il prodotto API alla chiave per ulteriori informazioni.

L'aggiunta di un prodotto API a una chiave dell'app consente all'app che contiene la chiave di accedere all'API in bundle nel prodotto API. La seguente chiamata al metodo aggiunge un nuovo prodotto API a un dell'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"
 }

Approva le chiavi utente

Impostando il tipo di approvazione su manuale puoi controllare quali gli sviluppatori possono accedere alle risorse protette dai prodotti basati su API. Quando i prodotti API hanno una chiave approvazione impostata su manual, le chiavi utente devono essere approvate esplicitamente. Le chiavi possono essere esplicitamente approvata utilizzando l'opzione Approva o revoca la chiave specifica dell'app sviluppatore API:

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

Vedi Approva o revoca chiave specifica dell'app sviluppatore per ulteriori informazioni.

Approva prodotti API per le chiavi utente

Anche l'associazione di un prodotto API a una chiave utente ha uno stato. Affinché l'accesso API sia riuscita, la chiave utente deve essere approvata e la chiave utente deve essere approvata il prodotto API appropriato. L'associazione di una chiave utente a un prodotto API può essere approvata mediante l'utilizzo di Approva o Revoca prodotto API per una chiave per uno sviluppatore API:

$ 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. Vedi Puoi approvare o revocare un prodotto API per una chiave di un'app sviluppatore per ulteriori informazioni.

Revoca prodotti API per chiavi utente

Esistono molti motivi per cui potrebbe essere necessario revocare l'associazione di una chiave utente a un'API prodotto. Potresti dover rimuovere un prodotto API da una chiave utente a causa di un mancato pagamento da parte di sviluppatore, un periodo di prova scaduto o la promozione di un'app da un prodotto API a un'altra.

Per revocare l'associazione di una chiave utente a un prodotto API, utilizza il pulsante Approva o revocare la chiave specifica dell'API dell'app sviluppatore , utilizzando l'azione di revoca rispetto al 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. Vedi Approva o revoca chiave specifica dell'app sviluppatore per ulteriori informazioni.

Applica impostazioni del prodotto API

Per applicare i prodotti API, deve essere collegato all'API uno dei seguenti tipi di norme flusso proxy:

  • VerificationAPIKey: prende un riferimento a una chiave API, verifica che rappresenti un'app valida e corrisponde al prodotto API. Consulta Verifica delle norme relative alle chiavi API per altro ancora.
  • OAuthV1, operazione "VerifyAccessToken": verifica la firma, convalida un il token di accesso OAuth 1.0a e la "chiave utente" e associa l'app al prodotto API. Consulta Criterio OAuth v1.0a per altro ancora.
  • OAuthV2, operazione "VerifyAccessToken": verifica che l'accesso OAuth 2.0 sia valido, lo associa all'app, verifica che l'app sia valida e poi abbina l'app a un prodotto API. Vedi OAuth home per saperne di più.

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

  1. Apigee Edge riceve una richiesta e viene instradata al proxy API appropriato.
  2. Viene eseguito un criterio che verifica la chiave API o il token di accesso OAuth presentato dal di alto profilo.
  3. Edge risolve la chiave API o il token di accesso in un profilo dell'app.
  4. Edge risolve l'elenco (se presente) di prodotti API associati all'app.
  5. Il primo prodotto API corrispondente viene utilizzato per compilare le variabili di quota.
  6. Se nessun prodotto API corrisponde alla chiave API o al token di accesso, la richiesta viene rifiutata.
  7. Edge applica il controllo degli accessi basato su URI (ambiente, proxy API e percorso URI) in base Impostazioni del prodotto API, oltre alle impostazioni delle quote.