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 l'Assistente codice Gemini 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 configurare la gestione delle API Apigee in Cloud Code per VS Code, inclusi l'utilizzo dell'Assistente codice Gemini con Apigee.
Assicurati che il tuo account utente abbia i ruoli richiesti elencati in Ruoli richiesti per utilizzare Gemini Code Assist in Apigee per ogni attività.

Scrivere prompt efficaci per le specifiche API

Dovrai richiedere l'Assistente codice Gemini in Apigee quando crei e modifichi le specifiche dell'API. L'accuratezza e l'idoneità delle specifiche dell'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 la chat di Gemini Code Assist, utilizza sempre l'handle Apigee (@Apigee) all'inizio dei prompt per creare o modificare le specifiche dell'API. L'handle Apigee consente di accedere allo strumento Apigee, che include le funzionalità di sviluppo delle specifiche API solide e complete descritte in questa guida.
Utilizza un linguaggio naturale:formula i prompt come se ti rivolgi a una persona che creerà la specifica.
Fornisci requisiti specifici:se possibile, fornisci requisiti esatti, ad esempio che l'API di pianificazione degli studi dentistici debba includere più tipi di appuntamenti e più sedi degli studi dentistici.
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. Sebbene non sia necessario specificare i nomi esatti degli oggetti, puoi suggerire questa funzionalità includendo nel prompt frasi come Use API Hub o Leverage Enterprise Context.
Utilizza i prompt di follow-up per eseguire l'iterazione sulle API: puoi utilizzare prompt come "Rimuovi l'entità locations da questa API" per apportare modifiche a un'API.

Di seguito sono riportati alcuni esempi di prompt meno e più efficaci per la creazione e la modifica delle specifiche dell'API:

Prompt meno efficace	Spiegazione del prompt	Prompt migliori
"Crea un'API per il mio negozio."	Questo prompt contiene informazioni troppo poche per consentire al modello di generare una specifica completa e accurata.	"Crea un'API per il mio negozio per consentire ai clienti di 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 di debito."
"Crea una nuova API di rimborso che riutilizzi l'oggetto ordine".	Non specificare quali oggetti deve riutilizzare Gemini Code Assist durante la creazione delle API. Gemini Code Assist rileva automaticamente gli oggetti più adatti da riutilizzare.	"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 online per la consegna di pizza personalizzata. Crea un'API per accettare gli ordini di pizza con dimensioni e condimenti." "API per attività di consegna di cibo. 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 patty. I panini hanno tipo di pane, tipo di carne, verdure, formaggio e istruzioni personalizzate."

Progettare API con Gemini Code Assist

Puoi utilizzare l'Assistente codice Gemini 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à in questa sezione.

Per generare una nuova API con Gemini Code Assist:

Utilizza uno dei seguenti metodi per accedere alla richiesta di creazione della specifica dell'API:
- Dall'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 Apigee. Viene caricato Gemini Code Assist: Chat. Richiama lo strumento Apigee con @Apigee per iniziare a creare le 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 dell'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 un file OAS che definisce l'API. (Questa operazione può richiedere fino a un minuto.) Se il tuo hub API include altre API, la nuova OAS potrebbe incorporare oggetti e contesto dal tuo catalogo. Il riepilogo della chat contestuale fornisce informazioni sull'API e sulle origini generate.
Rivedi la specifica generata. Sia la specifica del codice YAML sia 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 simulato.
Per salvare la nuova API nel catalogo dell'hub API, consulta Pubblicare le API nell'hub API.
Per creare un bundle di proxy API Apigee da questa specifica, consulta Salvare le API come bundle di proxy API.

Modificare le API

Puoi modificare le API salvate localmente o dal catalogo del tuo 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 il progetto 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 dell'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 la chat di Gemini Code Assist per eseguire l'iterazione della specifica.

Esegui l'iterazione sulle specifiche dell'API utilizzando la chat di Gemini Code Assist

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 per un file delle specifiche API locale.
Assicurati che il file YAML contenente la specifica sia la scheda attualmente attiva nell'editor.
Nella finestra della chat di Gemini Code Assist, inserisci l'handle Apigee, @Apigee, e seleziona lo strumento Apigee.
Inserisci il prompt di aggiornamento della specifica. Per indicazioni, consulta Scrivere prompt efficaci per le specifiche dell'API.
Se vuoi, puoi testare l'API utilizzando un server simulato.
Per salvare la nuova API nel catalogo dell'hub API, consulta Pubblicare le API nell'hub API.
Per creare un bundle di proxy API Apigee da questa specifica, consulta Salvare le API come bundle di proxy API.

Pubblicare le API nell'hub API

Se utilizzi API Hub, puoi mettere le tue API a disposizione di altri sviluppatori registrandole in API Hub:

Nel riquadro Swagger per una specifica dell'API nuova o modificata, fai clic su Pubblica nell'hub API.
Nel modulo, fornisci i metadati dell'API per migliorarne la rilevabilità e l'organizzazione all'interno del catalogo dell'hub API. La maggior parte dei campi viene compilata automaticamente dalla specifica dell'API, ma puoi modificare i valori. Consulta Registrare un'API per informazioni su come registrarti all'hub API e sulle informazioni da fornire.
- Nome visualizzato dell'API (obbligatorio): un nome dell'API visibile ad altri sviluppatori.
- Descrizione API (facoltativa): una descrizione dell'API per riferimento interno/sviluppatore.
- Nome proprietario dell'API (facoltativo): il nome del proprietario dell'API.
- Indirizzo email del proprietario dell'API (facoltativo): l'indirizzo email del proprietario.
- Versione API (obbligatoria): la versione dell'API.
- (Facoltativo) Fase del ciclo di vita: 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 nella struttura dell'hub API nella sezione Apigee di Cloud Code.

Testa le API utilizzando un server simulato

Puoi testare l'API utilizzando un server simulato locale o un Google Cloud-based remote mock server. Il server simulato locale è installato e disponibile per impostazione predefinita, mentre devi configurare e gestire Google Cloud i server simulati.

Utilizzare il server simulato locale

Il server simulato locale accetta le richieste a questa API ed emula le risposte. È utilizzabile solo durante la sessione corrente dall'utente corrente. Tuttavia, a differenza del server simulato remoto, non richiede configurazione o gestione e non comporta costi.

Inoltre, i server simulati locali:

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

Per utilizzare il server simulato locale:

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

Utilizzare un server simulato remoto

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

I server simulati remoti non si aggiornano automaticamente per le modifiche apportate all'API dopo il loro dispiegamento, quindi attendi di aggiungerli finché non hai creato completamente l'API.

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

Puoi utilizzare l'account di servizio predefinito o fornire un account di servizio con limitazioni maggiori per eseguire il deployment dell'applicazione Cloud Run. Per informazioni, consulta Gestire le API Cloud e le librerie client Cloud in Cloud Code per VS Code.

Per eseguire il deployment di un server simulato remoto:

Seleziona Esegui il deployment del server simulato dal riquadro Swagger.
Se la tua API non è ancora registrata in API Hub, registrala quando richiesto.
Specifica i dettagli del server simulato remoto: Nome server, Server sicuro, Account di servizio (lascia vuoto per utilizzare l'account di servizio predefinito) e se aggiungere l'URL del server alla specifica dell'API. Fai clic su Crea per creare il server simulato remoto.
Importante: non creare più server simulati remoti con lo stesso nome, anche se al momento l'interfaccia utente non lo impedisce.
La generazione del server simulato 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.
Al termine della procedura di creazione del server simulato 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 eventuali parametri di 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 invocatore per il servizio di cui è stato eseguito il deployment. Consulta Autenticare gli sviluppatori.
Quando effettuano la richiesta al server simulato, gli utenti seguono le istruzioni riportate in Testare il servizio privato.

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

Vai all' hub API Apigee.
Trova l'API per visualizzare tutti i relativi implementamenti, inclusi eventuali server simulati remoti.
Utilizza l'URL della risorsa per eseguire il deployment e gestirlo interrompendo, eliminando ed eseguendo altre azioni sul server simulato.

Salvare le API come bundle di proxy API

Puoi salvare l'API come bundle di proxy API Apigee in modo da poterci lavorare nel tuo ambiente di sviluppo locale Apigee. Per informazioni sull'utilizzo dei proxy API in Cloud Code, consulta Sviluppare proxy API.

Fai clic su Crea bundle di proxy API nel riquadro Swagger.
Nel campo del prompt, assegna 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 schema, metadati e definizioni di sicurezza di altre API della tua organizzazione. Il processo trova API simili utilizzando i nomi e le descrizioni degli oggetti. Lo stato di deployment delle API hub 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 al 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 è attivo in generale. Imposta 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 sugli schemi di altre API nell'hub API. includeSchema è applicabile solo quando enabled è impostato su true.
includeSecurity controlla se è incluso il contesto relativo 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.