Stai visualizzando la documentazione di Apigee Edge.
Consulta la
documentazione di Apigee X. informazioni
Pubblica le API sul tuo portale per renderle disponibili per l'uso da parte degli sviluppatori di app, come descritto nelle sezioni seguenti.
Panoramica della pubblicazione tramite API
Il processo di pubblicazione delle API sul portale prevede due fasi:
- Seleziona il prodotto API che vuoi pubblicare sul tuo portale.
- Rendering la documentazione di riferimento dell'API da un'istantanea del documento OpenAPI o dello schema GraphQL per consentire agli sviluppatori di app di acquisire informazioni sulle API. Per ulteriori informazioni sugli snapshot, consulta la sezione Che cos'è uno snapshot?.
Cosa viene pubblicato sul portale?
Quando pubblichi un'API, i seguenti aggiornamenti vengono apportati automaticamente al portale:La pagina delle API (inclusa nel portale di esempio) fornisce un elenco di tutte le API pubblicate sul tuo portale, elencate in ordine alfabetico, con link alla rispettiva documentazione di riferimento per le API. Se vuoi, puoi personalizzare quanto segue:
- Immagine visualizzata per ogni scheda dell'API
- Categorie utilizzate per il tagging delle API per consentire agli sviluppatori di scoprire le API correlate nella pagina delle API
SmartDocumenti (OpenAPI)
Quando pubblichi un'API utilizzando un documento OpenAPI, la documentazione di riferimento dell'API SmartDocs viene aggiunta al tuo portale.
Gli sviluppatori possono esaminare la documentazione di riferimento dell'API SmartDocs e utilizzare il riquadro Prova questa API per effettuare una richiesta API e visualizzare l'output. Prova questa API che funziona con endpoint non protetti o endpoint protetti utilizzando l'autenticazione base, chiave API o OAuth, in base al metodo di sicurezza definito nel documento OpenAPI. Per OAuth sono supportati i seguenti flussi: codice di autorizzazione, password e credenziali client.
Fai clic su per espandere il riquadro Prova questa API. Il riquadro espanso consente di visualizzare esempi di chiamata curl ed esempi di codice in vari formati, come HTTP, Python, Node.js e altri, come mostrato di seguito.
Explorer GraphQL
Quando pubblichi un'API utilizzando uno schema GraphQL, GraphQL Explorer viene aggiunto al portale. GraphQL Explorer è un parco giochi interattivo per l'esecuzione di query sulla tua API. L'esplorazione si basa su GraphiQL, un'implementazione di riferimento dell'IDE GraphQL sviluppata dalla GraphQL Foundation.
Gli sviluppatori possono utilizzare GraphQL Explorer per esplorare la documentazione interattiva basata su schema, creare ed eseguire query, visualizzare i risultati delle query e scaricare lo schema. Per proteggere l'accesso all'API, gli sviluppatori possono passare le intestazioni di autorizzazione nel riquadro Intestazioni della richiesta.
Per ulteriori informazioni su GraphQL, vedi graphql.org.
Che cos'è un'istantanea?
Ogni documento OpenAPI o GraphQL funge da fonte attendibile per tutto il ciclo di vita di un'API. Lo stesso documento viene utilizzato in ogni fase del ciclo di vita dell'API, dallo sviluppo alla pubblicazione fino al monitoraggio. Quando modifichi un documento, devi essere a conoscenza dell'impatto delle modifiche sull'API in altre fasi del ciclo di vita, come descritto in Cosa succede se modifico un documento?
Quando pubblichi l'API, acquisisci un'istantanea del documento OpenAPI o GraphQL per visualizzare la documentazione di riferimento dell'API. L'istantanea rappresenta una versione specifica del documento. Se modifichi il documento, puoi decidere di acquisire un'altra istantanea del documento per riflettere le ultime modifiche nella documentazione di riferimento dell'API.
Informazioni sugli URL di callback
Se le tue app richiedono un URL di callback, ad esempio quando utilizzi il tipo di autorizzazione del codice di autorizzazione OAuth 2.0 (spesso indicato come "OAuth a tre vie"), puoi richiedere agli sviluppatori di specificare un URL di callback quando registrano le loro app. L'URL di callback in genere specifica l'URL di un'app designata per ricevere un codice di autorizzazione per conto dell'app client. Per ulteriori informazioni, consulta Implementazione del tipo di concessione del codice di autorizzazione.
Puoi configurare se richiedere o meno un URL di callback durante la registrazione dell'app quando aggiungi un'API al tuo portale. Puoi modificare questa impostazione in qualsiasi momento, come descritto in Gestire l'URL di callback per un'API.
Quando registrano un'app, gli sviluppatori devono inserire un URL di callback per tutte le API che lo richiedono, come descritto nella sezione Registrare le app.
Configura il proxy API in modo che supporti "Prova questa API"
Prima di pubblicare le API utilizzando un documento OpenAPI, devi configurare il proxy API per supportare l'esecuzione di richieste nel riquadro Prova questa API nella documentazione di riferimento dell'API SmartDocs, come indicato di seguito:
- Aggiungi il supporto CORS ai proxy API per applicare le richieste multiorigine lato client
CORS è un meccanismo standard che consente alle chiamate JavaScript XMLHttpRequest (XHR) eseguite in una pagina web di interagire con le risorse dei domini non di origine. CORS è una soluzione comunemente implementata al "criterio della stessa origine" applicato da tutti i browser.
- Aggiorna la configurazione del proxy API se utilizzi l'autenticazione di base o OAuth2
La tabella seguente riassume i requisiti di configurazione del proxy API per il supporto del riquadro Prova questa API nella documentazione di riferimento dell'API SmartDocs in base all'accesso all'autenticazione.
Accesso di autorizzazione | Requisiti di configurazione dei criteri |
---|---|
Nessuna o chiave API | Aggiungi il supporto CORS al tuo proxy API. Per comodità, utilizza la soluzione CORS di esempio fornita su GitHub o segui i passaggi descritti in Aggiungere il supporto CORS a un proxy API. |
Autenticazione di base | Svolgi i seguenti passaggi:
|
OAuth2 |
|
Esplorare il catalogo delle API
Per visualizzare il catalogo delle API: 1. Seleziona Pubblica > Portali e seleziona il tuo portale. 2. Fai clic su Catalogo API nella home page del portale. In alternativa, puoi selezionare Catalogo API nel menu a discesa del portale nella barra di navigazione in alto.
La scheda API nel catalogo delle API mostra un elenco delle API aggiunte al portale.
Come evidenziato nella figura precedente, la scheda API ti consente di:
- Visualizza i dettagli delle API disponibili nel portale
- Aggiungi un'API al portale
- Modifica un'API sul tuo portale eseguendo una o più delle seguenti attività:
- Gestire lo snapshot di un documento associato a un prodotto API per aggiornare la documentazione di riferimento dell'API
- Pubblicare o annullare la pubblicazione di un'API sul portale
- Gestisci la visibilità di un'API nel tuo portale:
- Gestire l'URL di callback per un'API
- Gestire l'immagine per una scheda API
- Codifica di un'API utilizzando le categorie
- Modificare il titolo e la descrizione dell'API
- Rimuovere un'API dal portale
- Gestire le categorie utilizzate per scoprire le API correlate
- Identificare rapidamente le specifiche obsolete o che sono state eliminate dall'archivio delle specifiche
- Identifica rapidamente le API "orfane" il cui prodotto API associato è stato rimosso da Edge e ricrea il prodotto API o elimina l'API dal portale
Aggiungi un'API al portale
Per aggiungere un'API al portale:
- Accedi al catalogo delle API.
- Fai clic sulla scheda API, se non è già selezionata.
Fai clic su +.
Viene visualizzata la finestra di dialogo Aggiungi un prodotto API al catalogo.
Seleziona il prodotto API che vuoi aggiungere al tuo portale.
Fai clic su Avanti. Viene visualizzata la pagina dei dettagli dell'API.
Configura i contenuti della documentazione di riferimento dell'API e la sua visibilità sul portale:
Tecnico Descrizione Pubblicato Seleziona Published (Pubblicata) per pubblicare l'API sul tuo portale. Deseleziona la casella di controllo se non sei pronto per pubblicare l'API. Puoi modificare l'impostazione in un secondo momento, come descritto in Pubblicare o annullare la pubblicazione di un'API sul portale. Titolo visualizzato Aggiorna il titolo dell'API visualizzato nel catalogo. Per impostazione predefinita, viene utilizzato il nome del prodotto API. Puoi modificare il titolo visualizzato in un secondo momento, come descritto nella sezione Modificare il titolo visualizzato e la descrizione. Visualizza descrizione Aggiorna la descrizione dell'API visualizzata nel catalogo. Per impostazione predefinita, viene utilizzata la descrizione del prodotto API. Puoi modificare la descrizione da visualizzare in un secondo momento, come descritto nella sezione Modificare il titolo e la descrizione visualizzati. Imponi agli sviluppatori di specificare un URL di callback Attiva questa opzione se vuoi richiedere agli sviluppatori di app di specificare un URL di callback. Puoi aggiungere o aggiornare l'URL di callback in un secondo momento, come descritto in Gestire l'URL di callback per un'API. Documentazione relativa all'API Per utilizzare un documento OpenAPI: - Seleziona Documento OpenAPI.
- Fai clic su Seleziona documento.
- Esegui uno dei seguenti passaggi:
- Fai clic sulla scheda Le mie specifiche e seleziona una specifica dallo store delle specifiche.
- Fai clic sulla scheda Carica file e carica un file.
- Fai clic sulla scheda Importa da un URL e importa una specifica da un URL.
- Fai clic su Seleziona.
Per utilizzare uno schema GraphQL:
- Seleziona Diagramma grafico.
- Fai clic su Seleziona documento.
- Vai allo schema GraphQL e selezionalo.
- Fai clic su Seleziona.
In alternativa, puoi selezionare Nessuna documentazione e aggiungerne una in un secondo momento dopo l'aggiunta dell'API, come descritto in Gestire lo snapshot del documento.
Visibilità API Se non hai effettuato la registrazione alla versione beta della funzionalità di gestione dei segmenti di pubblico, seleziona una delle seguenti opzioni:
- Utenti anonimi per consentire a tutti gli utenti di visualizzare l'API.
- Utenti registrati per consentire solo agli utenti registrati di visualizzare l'API.
Se hai eseguito la registrazione alla release beta della funzionalità di gestione dei segmenti di pubblico, seleziona una delle seguenti opzioni:
- Pubblica (visibile a tutti) per consentire a tutti gli utenti di visualizzare l'API.
- Utenti autenticati per consentire solo agli utenti registrati di visualizzare l'API.
- Segmenti di pubblico selezionati per scegliere i segmenti di pubblico specifici che vuoi che possano visualizzare l'API.
Puoi gestire la visibilità del pubblico in un secondo momento, come descritto in Gestire la visibilità di un'API nel portale.
Visualizza immagine Per visualizzare un'immagine sulla scheda dell'API, fai clic su Seleziona immagine. Nella finestra di dialogo Seleziona immagine, seleziona un'immagine esistente, carica una nuova immagine o fornisci l'URL di un'immagine esterna e fai clic su Seleziona. Visualizza l'anteprima della miniatura dell'API e fai clic su Seleziona. Puoi aggiungere un'immagine in un secondo momento, come descritto in Gestire l'immagine per una scheda API. Quando specifichi un'immagine con un URL esterno, l'immagine non viene caricata negli asset. Inoltre, il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dalle norme sulla sicurezza del contenuto. Categorie Aggiungi le categorie in cui l'API sarà codificata per consentire agli sviluppatori di app di scoprire le API correlate nella pagina delle API. Per identificare una categoria:
- Seleziona una categoria dall'elenco a discesa.
- Aggiungi una nuova categoria digitando il nome e premendo Invio. La nuova categoria verrà aggiunta alla pagina Categorie e resa disponibile durante l'aggiunta o la modifica di altre API.
Fai clic su Salva.
Gestisci l'istantanea del documento
Dopo aver pubblicato l'API, puoi acquisire in qualsiasi momento un nuovo snapshot del documento OpenAPI o GraphQL per aggiornare la documentazione di riferimento dell'API pubblicata sul tuo portale.
Per gestire l'istantanea del documento:
- Accedi al catalogo delle API.
- Fai clic sulla scheda API, se non è già selezionata.
- Fai clic sulla riga dell'API che vuoi modificare.
- Controlla lo stato dello snapshot. Se non è aggiornato, viene visualizzato il seguente messaggio:
- Fai clic su .
- Esegui una delle seguenti attività:
- Per aggiornare l'istantanea di un documento OpenAPI non aggiornato, fai clic su Aggiorna snapshot.
- Per modificare il documento utilizzato per generare la documentazione per l'API, nella documentazione dell'API fai clic su Seleziona documento e seleziona il nuovo documento.
- Fai clic su Salva.
La documentazione di riferimento delle API viene visualizzata dal documento e aggiunta alla pagina Riferimento API. Lo stato dello snapshot viene aggiornato a attuale:
Pubblicare o annullare la pubblicazione di un'API sul portale
Per pubblicare o annullare la pubblicazione di un'API sul tuo portale:
- Accedi al catalogo delle API.
- Fai clic sulla scheda API, se non è già selezionata.
- Fai clic sulla riga dell'API che vuoi modificare.
- Fai clic su .
- In Dettagli API, seleziona o deseleziona Pubblicata (elencata nel catalogo) per pubblicare o annullare la pubblicazione dell'API sul tuo portale.
- Fai clic su Salva.
Gestisci la visibilità di un'API nel tuo portale
Gestisci la visibilità di un'API nel tuo portale consentendo l'accesso a:
- Pubblico (visibile a tutti)
- Utenti autenticati
- Segmenti di pubblico selezionati (se hai eseguito la registrazione alla release beta della funzionalità di gestione dei segmenti di pubblico)
Per gestire la visibilità di un'API nel tuo portale:
- Accedi al catalogo delle API.
- Fai clic sulla scheda API, se non è già selezionata.
- Fai clic sulla riga dell'API che vuoi modificare.
- Fai clic su .
- In Visibilità API, seleziona una delle seguenti opzioni:
Seleziona l'impostazione di visibilità. Se hai eseguito la registrazione alla release beta della funzionalità Segmenti di pubblico, seleziona una delle seguenti opzioni:
- Pubblica (visibile a tutti) per consentire a tutti gli utenti di visualizzare la pagina.
- Utenti autenticati per consentire solo agli utenti registrati di visualizzare la pagina.
- Segmenti di pubblico selezionati per scegliere i segmenti di pubblico specifici che vuoi che possano visualizzare la pagina. Vedi Gestire i segmenti di pubblico per il portale.
- Utenti anonimi per consentire a tutti gli utenti di visualizzare la pagina.
- Utenti registrati per consentire solo agli utenti registrati di visualizzare la pagina.
Fai clic su Invia.
Gestire l'URL di callback per un'API
Gestisci l'URL di callback per un'API. Consulta Informazioni sugli URL di callback.
Per gestire l'URL di callback per un'API:
- Accedi al catalogo delle API.
- Fai clic sulla scheda API, se non è già selezionata.
- Fai clic sulla riga dell'API che vuoi modificare.
- Fai clic su .
- In Dettagli API, seleziona o deseleziona Pubblicata (elencata nel catalogo) per pubblicare o annullare la pubblicazione dell'API sul tuo portale.
- Fai clic su Salva.
Gestisci l'immagine per una scheda API
Gestisci l'immagine che viene visualizzata con una scheda API nella pagina delle API aggiungendo o modificando l'immagine corrente.
Per gestire l'immagine per una scheda API:
- Accedi al catalogo delle API.
- Fai clic sulla scheda API, se non è già selezionata.
- Fai clic sulla riga dell'API che vuoi modificare.
- Fai clic su .
In Dettagli API:
- Fai clic su Seleziona immagine per specificare o caricare un'immagine se al momento non è selezionata nessuna immagine.
- Fai clic su Cambia immagine per specificare o caricare un'immagine diversa.
- Fai clic sulla x nell'immagine per rimuoverla.
Quando specifichi un'immagine, specifica un'immagine con un URL esterno utilizzato per l'articolo del catalogo oppure un percorso file per i file immagine archiviati nel portale, ad esempio
/files/book-tree.jpg
. Quando specifichi l'URL di un'immagine esterna, l'immagine non verrà caricata negli asset. Inoltre, il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dai criteri di sicurezza dei contenuti.Fai clic su Salva.
Applica il tagging a un'API utilizzando le categorie
Applica il tagging a un'API utilizzando le categorie in uno dei seguenti modi:
- Gestisci le categorie in cui un'API è codificata durante la modifica dell'API, come descritto di seguito.
- Gestisci le API codificate in una categoria durante la modifica della categoria.
Per assegnare a un'API le categorie quando modifichi l'API:
- Accedi al catalogo delle API.
- Fai clic sulla scheda API, se non è già selezionata.
- Fai clic sulla riga dell'API che vuoi modificare.
- Fai clic su .
- Fai clic nel campo Categorie ed esegui uno dei seguenti passaggi:
- Seleziona una categoria dall'elenco a discesa.
- Aggiungi una nuova categoria digitando il nome e premendo Invio. La nuova categoria verrà aggiunta alla pagina Categorie e resa disponibile durante l'aggiunta o la modifica di altre API.
- Ripeti la procedura per aggiungere l'API ad altre categorie.
- Fai clic su Salva.
Modifica il titolo visualizzato e la descrizione
Per modificare il titolo e la descrizione visualizzati:
- Accedi al catalogo delle API.
- Fai clic sulla scheda API, se non è già selezionata.
- Fai clic sulla riga dell'API che vuoi modificare.
- Fai clic su .
- Modifica i campi Titolo visualizzato e Descrizione visualizzata, come richiesto.
- Fai clic su Salva.
Rimuovere un'API dal portale
Per rimuovere un'API dal portale:
- Accedi al catalogo delle API.
- Seleziona le API, se non sono già selezionate.
- Posiziona il cursore sull'API nell'elenco per visualizzare il menu Azioni.
- Fai clic su .
Gestisci le categorie utilizzate per scoprire le API correlate
Codifica un'API utilizzando le categorie per consentire agli sviluppatori di app di scoprire le API correlate nella pagina API del portale in tempo reale. Aggiungi e gestisci le categorie, come descritto nelle sezioni seguenti.
Esplorare la pagina Categorie
Per visualizzare la pagina Categorie:
- Seleziona Pubblica > Portali e seleziona il tuo portale.
- Fai clic su Catalogo API nella home page del portale.
In alternativa, puoi selezionare Catalogo API nel menu a discesa del portale nella barra di navigazione in alto.
- Fai clic sulla scheda Categorie.
La scheda Categorie nel catalogo delle API mostra l'elenco delle categorie che sono state definite per il portale.
Come evidenziato nella figura precedente, la pagina delle API ti consente di:
- Visualizzare le categorie e le API in cui sono taggati
- Aggiungi una categoria
- Modificare una categoria
- Eliminare una categoria
- Gestisci le API pubblicate sul tuo portale. Consulta Esplorare il catalogo delle API
Aggiunta di una categoria
Aggiungi una categoria in uno dei seguenti modi:
- Inserisci il nome di una categoria quando aggiungi un'API al portale
- Aggiungi manualmente una categoria come descritto di seguito
La nuova categoria verrà aggiunta alla pagina Categorie e resa disponibile durante l'aggiunta o la modifica di altre API.
Per aggiungere manualmente una categoria:
- Accedi alla pagina Categorie.
- Fai clic su +.
- Inserisci il nome della nuova categoria.
- (Facoltativo) Seleziona una o più API da taggare per la categoria.
- Fai clic su Crea.
Modificare una categoria
Per modificare una categoria:
- Accedi alla pagina Categorie.
- Fai clic su .
- Modifica il nome della categoria.
- Aggiungi o rimuovi i tag API.
- Fai clic su Salva.
Eliminare una categoria
Quando elimini una categoria, vengono eliminati anche tutti i tag API relativi a quella categoria.
Per eliminare una categoria:
- Accedi alla pagina Categorie.
- Posiziona il cursore sulla categoria da modificare per visualizzare il menu Azioni.
- Fai clic su .
- Modifica il nome della categoria.
- Aggiungi o rimuovi API.
- Fai clic su Salva.
Risolvere i problemi relativi alle API pubblicate
Le seguenti sezioni forniscono informazioni utili per la risoluzione di errori specifici relativi alle nostre API pubblicate.
Errore: impossibile recuperare l'errore restituito durante l'utilizzo di Prova questa API
Quando utilizzi Prova questa API, se viene restituito l'errore TypeError: Failed to fetch
, prendi in considerazione le seguenti possibili cause e soluzioni:
In caso di errori di contenuti misti, l'errore potrebbe essere causato da un problema noto dell'interfaccia utente. Una possibile soluzione alternativa consiste nell'assicurarti di specificare HTTPS prima di HTTP nella definizione di
schemes
del documento OpenAPI. Ad esempio:schemes: - https - http
In caso di errori relativi alle limitazioni di condivisione delle risorse tra origini (CORS), assicurati che CORS sia supportato per i proxy API. CORS è un meccanismo standard che consente le richieste multiorigine lato client. Vedi Configurare il proxy API per il supporto di Prova questa API.
Errore: l'intestazione "Access-Control-Allow-Origin" contiene più valori "*, *", ma ne è consentito solo uno
Quando utilizzi Prova questa API, potresti ricevere il seguente messaggio di errore se l'intestazione Access-Control-Allow-Origin
esiste già:
The 'Access-Control-Allow-Origin' header contains multiple values '*, *', but only one is allowed.
Per correggere questo errore, modifica il criterio di AttributionMessage in modo da utilizzare <Set>
per impostare le intestazioni CORS anziché <Add>
, come mostrato nell'estratto di seguito.
Per ulteriori informazioni, consulta l'articolo della community pertinente.
<AssignMessage async="false" continueOnError="false" enabled="true" name="add-cors"> <DisplayName>Add CORS</DisplayName> <FaultRules/> <Properties/> <Set> <Headers> <Header name="Access-Control-Allow-Origin">{request.header.origin}</Header> <Header name="Access-Control-Allow-Headers">origin, x-requested-with, accept, content-type, authorization</Header> <Header name="Access-Control-Max-Age">3628800</Header> <Header name="Access-Control-Allow-Methods">GET, PUT, POST, DELETE</Header> </Headers> </Set> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> <AssignTo createNew="false" transport="http" type="response"/> </AssignMessage>
Errore: campo intestazione della richiesta non consentito
Quando utilizzi Prova questa API, se ricevi un errore Request header field not allowed
simile all'esempio riportato di seguito, potresti dover aggiornare le intestazioni supportate nel criterio CORS. Ad esempio:
Access to XMLHttpRequest ... has been blocked by CORS policy: Request header field
content-type is not allowed by Access-Control-Allow-Headers in preflight response
In questo esempio, devi aggiungere l'intestazione content-type
alla sezione Access-Control-Allow-Headers
nel criterio di AttributionMessage di CORS, come descritto in
Collegare un criterio CORS a un nuovo proxy API.
Errore: accesso negato durante la chiamata a un proxy API tramite OAuth2
Il criterio OAuthV2 di Apigee restituisce una risposta al token contenente determinate proprietà non conformi a RFC. Ad esempio, il criterio restituirà un token con il valore BearerToken
, invece del valore previsto conforme a RFC Bearer
. Questa risposta token_type
non valida può causare un errore Access denied
quando utilizzi Prova questa API.
Per risolvere il problema, puoi creare un criterio JavaScript o AttributionMessage per trasformare l'output del criterio in un formato conforme. Per maggiori informazioni, vedi comportamento non conforme a RFC.