Questa pagina è stata tradotta dall'API Cloud Translation.

Progettazione e modifica delle API

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina fornisce istruzioni su come progettare e modificare le API in Apigee in Cloud Code, sfruttando Gemini Code Assist per accelerare la creazione, la modifica e la gestione delle specifiche API.

Prima di iniziare

Prima di utilizzare la funzionalità descritta in questa guida:

Assicurati di aver completato i passaggi di configurazione per Configurazione della gestione delle API Apigee in Cloud Code per VS Code, inclusi Utilizzo dell'Assistente codice Gemini con Apigee.
Assicurati che il tuo account utente disponga dei ruoli richiesti elencati in Ruoli richiesti per utilizzare Gemini Code Assist in Apigee per ogni attività.

Scrivere prompt efficaci per le specifiche API

Quando crei e modifichi le specifiche API, devi richiedere l'intervento di Gemini Code Assist in Apigee. L'accuratezza e l'idoneità delle specifiche API generate dipendono in gran parte dai prompt forniti al modello.

Per scrivere prompt efficaci per la creazione e la modifica delle specifiche API:

Con Gemini Code Assist Chat, utilizza sempre l'handle Apigee (@Apigee) all'inizio dei prompt per creare o modificare le specifiche API. L'handle Apigee ti consente di accedere allo strumento Apigee, che include le funzionalità di sviluppo delle specifiche API robuste e ricche di funzionalità descritte in questa guida.
Usa un linguaggio naturale:formula i prompt come se ti stessi rivolgendo a una persona che creerà le specifiche.
Sii specifico:fornisci requisiti esatti, ove possibile, ad esempio che l'API di pianificazione dello studio dentistico deve includere più tipi di appuntamenti e più sedi dello studio dentistico.
Sfrutta il contesto aziendale senza specificare i nomi degli oggetti: Gemini Code Assist rileva e riutilizza in modo intelligente schemi, metadati e definizioni di sicurezza esistenti dal catalogo dell'hub API. Anche se non è necessario specificare i nomi esatti degli oggetti, puoi suggerire questa funzionalità includendo frasi come Use API Hub o Leverage Enterprise Context nel prompt.
Utilizza prompt di follow-up per iterare sulle tue API: puoi utilizzare prompt come "Rimuovi l'entità località da questa API" per apportare modifiche a un'API.

Ecco alcuni esempi di prompt meno ed efficaci per creare e modificare le specifiche API:

Prompt meno efficace	Spiegazione del prompt	Prompt migliori
"Crea un'API per il mio negozio."	Questo prompt contiene troppo poche informazioni per consentire al modello di generare una specifica completa e accurata.	"Crea un'API per il mio negozio in modo che i clienti possano verificare la disponibilità dei prodotti e aggiungere articoli al carrello degli acquisti." "Crea un'API che consenta ai clienti di pagare un ordine utilizzando vari metodi di pagamento come carte di credito e carte di debito".
"Crea una nuova API di rimborso che riutilizzi l'oggetto ordine."	Non specificare quali oggetti devono essere riutilizzati da Gemini Code Assist durante la creazione delle API. Gemini Code Assist rileva automaticamente gli oggetti più adatti al riutilizzo.	"Crea una nuova API di rimborso che consenta ai clienti di richiedere un rimborso per un ordine precedente."
"Crea un'API per un servizio di consegna."	L'API generata sarà troppo generica.	"Siamo una pizzeria e vogliamo una soluzione di consegna di pizza online personalizzata. Crea un'API per accettare gli ordini di pizza con dimensioni e condimenti." "API per attività di consegna di pasti a domicilio. I clienti possono ordinare una combinazione di pizza, hamburger o panini in un unico ordine. Ciascuno di questi tipi di alimenti ha il proprio schema. Le pizze hanno condimenti e dimensioni. Gli hamburger hanno condimenti e tipo di carne. I panini hanno tipo di pane, tipo di carne, verdure, formaggio e istruzioni personalizzate".

Progettare API con Gemini Code Assist

Puoi utilizzare Gemini Code Assist in Cloud Code per progettare API con specifica OpenAPI (OAS), versione 3.0. Le API progettate possono includere il contesto aziendale durante la generazione di nuove API e sono disponibili solo con i progetti che utilizzano l'hub API.

Consulta la sezione Prima di iniziare per informazioni sui passaggi di configurazione per l'utilizzo della funzionalità descritta in questa sezione.

Per generare una nuova API con Gemini Code Assist:

Utilizza uno di questi metodi per accedere al prompt di creazione della specifica API:
- Da Assistente codice Gemini: chat: nella finestra della chat, inserisci l'handle Apigee, @Apigee, e seleziona lo strumento Apigee.
- Da Apigee in Cloud Code: fai clic sulla bacchetta magica nella riga di Apigee. Viene caricato Gemini Code Assist: Chat. Richiama lo strumento Apigee con @Apigee per iniziare la creazione delle specifiche.
Seleziona Crea specifica API dalle opzioni dello strumento Apigee.
Completa il prompt con una descrizione della nuova API. Consulta Scrivere prompt efficaci per le specifiche API. Non copiare e incollare sopra l'handle @Apigee. Completa invece il prompt digitando o incollando il testo dopo l'handle.)
Invia il prompt.
Gemini Code Assist genera una specifica OAS che definisce l'API. (Questa operazione può richiedere fino a un minuto.) Se l'hub API include altre API, il nuovo OAS potrebbe incorporare oggetti e contesto dal catalogo. Il riepilogo della chat contestuale fornisce informazioni sull'API generata e sulle fonti utilizzate.
Rivedi la specifica generata. Sia la specifica del codice YAML che il riquadro Swagger per la nuova API vengono visualizzati automaticamente nelle schede.
Una volta completata la nuova specifica, puoi testarla utilizzando un server simulato. Consulta Testare l'API utilizzando un server di simulazione.
Per salvare la nuova API nel catalogo dell'hub API, consulta Pubblicare API nell'hub API.
Per creare un bundle del proxy API Apigee da questa specifica, consulta Salva le API come bundle del proxy API.

Modifica API

Puoi modificare le API che hai salvato localmente o dal catalogo dell'hub API. Le modifiche apportate in Cloud Code possono essere salvate nell'hub API o salvate come bundle di proxy API Apigee.

Modificare una specifica API dall'hub API

Per modificare una specifica API archiviata nel catalogo dell'hub API:

Assicurati che il progetto selezionato in Cloud Code sia quello con il catalogo dell'hub API contenente l'API che vuoi modificare.
Nel riquadro di navigazione a sinistra, espandi l'albero API Hub nella sezione Apigee.
Seleziona l'API e la versione da modificare dall'elenco.
Visualizza le operazioni API nel riquadro Swagger. Fai clic su Visualizza codice nel riquadro Swagger per aprire il file YAML in una scheda di modifica.

Modificare una specifica API memorizzata localmente

Per modificare una specifica API archiviata localmente, apri il file della specifica API in Cloud Code. Puoi aggiornare manualmente la specifica o utilizzare Gemini Code Assist Chat per iterare la specifica.

Iterare sulle specifiche delle API utilizzando Gemini Code Assist Chat

Puoi apportare modifiche a una specifica API esistente utilizzando la chat di Gemini Code Assist:

Carica il file delle specifiche in Cloud Code seguendo le istruzioni per una specifica API dall'hub API o un file delle specifiche API locale.
Assicurati che il file YAML contenente la specifica sia la scheda attualmente attiva nell'editor.
Nella finestra di chat di Gemini Code Assist, inserisci l'handle Apigee, @Apigee, e seleziona lo strumento Apigee.
Inserisci il prompt di aggiornamento delle specifiche. Consulta la sezione Scrivere prompt efficaci per le specifiche API per indicazioni.
(Facoltativo) Testa l'API utilizzando un server simulato.
Per salvare la nuova API nel catalogo dell'hub API, consulta Pubblicare API nell'hub API.
Per creare un bundle di proxy API Apigee da questa specifica, consulta Salva le API come bundle di proxy API.

Pubblicare le API nell'hub API

Se utilizzi l'hub API, puoi rendere le tue API disponibili per altri sviluppatori registrandole nell'hub API:

Nel riquadro Swagger per una specifica API nuova o modificata, fai clic su Pubblica nell'hub API.
Nel modulo, fornisci i metadati per l'API per migliorarne la rilevabilità e l'organizzazione all'interno del catalogo dell'hub API. La maggior parte dei campi viene compilata automaticamente dalle specifiche dell'API, ma puoi modificare i valori. Consulta la sezione Registrare un'API per informazioni sulla registrazione all'hub API e sulle informazioni che devi fornire.
- Nome visualizzato API (obbligatorio): un nome dell'API visibile ad altri sviluppatori.
- Descrizione API (facoltativo): una descrizione dell'API per riferimento interno/per sviluppatori.
- Nome proprietario API (facoltativo): il nome del proprietario dell'API.
- Email del proprietario dell'API (facoltativo): l'indirizzo email del proprietario.
- Versione API (obbligatorio): la versione dell'API.
- Fase del ciclo di vita (facoltativo): seleziona una fase dall'elenco.
Fai clic su Pubblica per pubblicare l'API nell'hub API.
Dopo un breve ritardo, le modifiche dovrebbero essere visibili nell'albero dell'hub API nella sezione Apigee di Cloud Code.

Testare le API utilizzando un server simulato

Puoi testare l'API utilizzando un server mock locale o un server mock remoto basato su Google Cloud. Il server di simulazione locale è installato e disponibile per impostazione predefinita, mentre devi configurare e gestire Google Cloud i server di simulazione.

Utilizzare il server di simulazione locale

Il server di simulazione locale accetta le richieste a questa API ed emula le risposte. Può essere utilizzato solo durante la sessione corrente dall'utente corrente. Tuttavia, a differenza del server di simulazione remoto, non richiede configurazione o gestione e non comporta costi.

Inoltre, server di simulazione locali:

Non funzionano quando utilizzi Cloud Shell Editor o Cloud Workstations.
Potrebbe non funzionare correttamente quando si utilizza VS Code Remote Explorer.

Per utilizzare il server di simulazione locale:

Seleziona il server di simulazione locale nel menu a discesa Server (se non è già selezionato):
Apri un percorso nel riquadro Swagger e fai clic su Prova.
Compila i parametri della richiesta e fai clic su Esegui.

Utilizzare un server di simulazione remoto

Un server di simulazione remoto consente di creare un'istanza di server di simulazione persistente che, a differenza del server di simulazione locale, può essere condivisa e utilizzata da altri utenti della tua organizzazione per testare la nuova API. I server di simulazione remoti possono essere utilizzati solo con le API registrate nell'hub API.

I server di simulazione remoti non vengono aggiornati automaticamente per le modifiche apportate all'API dopo il deployment del server di simulazione, quindi attendi di aggiungere il server di simulazione finché non hai creato completamente l'API.

Il deployment di un Google Cloud server di simulazione remoto crea un nuovo servizio Cloud Run. Crea un'immagine container per il server di simulazione utilizzando Cloud Build e la carica in Cloud Artifact Registry nel tuo progetto Google. Consulta Che cos'è Cloud Run? Gestione dei servizi e la documentazione di Artifact Registry.

Puoi utilizzare il account di servizio predefinito o fornire unaccount di serviziot più limitato per il deployment dell'applicazione Cloud Run. Per informazioni, consulta Gestire le API Cloud e le librerie client di Cloud in Cloud Code per VS Code.

Per eseguire il deployment di un server di simulazione remoto:

Seleziona Esegui il deployment del server di simulazione dal pannello Swagger.
Se la tua API non è ancora registrata nell'hub API, registrala quando ti viene richiesto.
Specifica i dettagli del server di simulazione remoto: Nome server, Server sicuro, Service Account (lascia vuoto per utilizzare il account di servizio predefinito) e se aggiungere l'URL del server alla specifica API. Fai clic su Crea per creare il server di simulazione remoto.
Importante: non creare più server di simulazione remoti con lo stesso nome, anche se l'interfaccia utente non ti impedisce di farlo in questo momento.
La generazione del server di simulazione remoto richiede diversi minuti. Puoi monitorare l'avanzamento nel pannello OUTPUT di Cloud Code e tramite il popup di notifica nell'angolo in basso a destra di VS Code.
Una volta completata la procedura di creazione del server di simulazione remoto, vedrai l'URL del server remoto nell'elenco dei server del riquadro Swagger e nel riquadro OUTPUT.
Per utilizzare il server simulato, apri un percorso e fai clic su Prova.

Compila i parametri della richiesta e fai clic su Esegui.

Puoi anche inviare richieste utilizzando curl da un prompt. Utilizza l'indirizzo e la porta del server dal menu a discesa Server.

Per condividere l'accesso al server simulato con altri utenti:

Assegna ad altri utenti il ruolo di invoker per il servizio di cui è stato eseguito il deployment. Consulta Autenticare gli sviluppatori.
Quando inviano la richiesta al server simulato, gli utenti seguono le istruzioni riportate in Testare il servizio privato.

Per gestire i server di simulazione remoti di cui è stato eseguito il deployment:

Vai all' hub API Apigee.
Trova l'API per visualizzare tutti i deployment, inclusi eventuali server mock remoti.
Utilizza l'URL risorsa per accedere al deployment e gestirlo interrompendo, eliminando ed eseguendo altre azioni sul server di simulazione.

Salvare le API come bundle di proxy API

Puoi salvare la tua API come bundle di proxy API Apigee in modo da poterla utilizzare all'interno del tuo ambiente di sviluppo locale Apigee. Per informazioni sull'utilizzo dei proxy API in Cloud Code, vedi Sviluppare proxy API.

Fai clic su Crea bundle proxy API nel riquadro Swagger.
Nel campo del prompt, dai un nome al proxy API e continua.
Il proxy API viene visualizzato nel menu a sinistra di Apigee nello spazio di lavoro locale, in apiproxies.

Controllare il contesto aziendale nella generazione delle specifiche

La generazione di OAS può includere definizioni di schema, metadati e sicurezza dalle altre API della tua organizzazione. Il processo trova API simili utilizzando i nomi e le descrizioni degli oggetti. Lo stato di deployment delle API dell'hub API non viene preso in considerazione.

Il contesto aziendale è abilitato per impostazione predefinita.

Per disattivare il contesto aziendale per la generazione di nuove specifiche, aggiungi queste righe nel file settings.json dopo "cloudcode.apigee.gemini.enable": true:

"cloudcode.apigee.gemini.options": {
         "enterpriseContext": {
           "enabled": false,
           "includeMetadata": false,
           "includeSchema": false,
           "includeSecurity": false
         }
     }

Dove:

enabled specifica se il contesto aziendale è abilitato nel complesso. Imposta questo parametro su false per disattivare il contesto aziendale.
includeMetadata controlla se il contesto dei metadati è incluso. Questa impostazione include o esclude i metadati di altre API nell'hub API. includeMetadata è applicabile solo quando enabled è impostato su true.
includeSchema controlla se il contesto dello schema è incluso. Questa impostazione include o esclude le informazioni sullo schema di altre API nell'hub API. includeSchema è applicabile solo quando enabled è impostato su true.
includeSecurity controlla se è incluso il contesto correlato alla sicurezza. Questa impostazione include o esclude le informazioni sulla sicurezza di altre API nell'hub API. includeSecurity è applicabile solo quando enabled è impostato su true.