Progettazione e modifica di API

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

Segui le istruzioni in questa pagina per utilizzare Cloud Code per progettare e modificare le API.

Progetta le API con Gemini Code Assist

Anteprima - Gemini Code Assist

Questa funzionalità è soggetta ai "Termini delle Offerte pre-GA" nella sezione Termini generali del servizio dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per saperne di più, consulta le descrizioni della fase di lancio.

Puoi utilizzare Cloud Code per progettare API della specifica OpenAPI (OAS), versione 3.0, utilizzando Gemini Code Assist. Gemini Code Assist può includere un contesto aziendale per l'assistenza dell'AI generativa nel processo di sviluppo dell'API. Il contesto aziendale utilizza le API dell'hub API del progetto come contesto durante la generazione di nuove API ed è disponibile solo per i progetti che utilizzano l'hub API.

Consulta Utilizzare Gemini Code Assist per informazioni sulla procedura di configurazione per l'utilizzo della funzionalità in questa sezione.

Nota: al momento Gemini Code Assist supporta la progettazione di API che combinano nuovi oggetti con oggetti esistenti (se il contesto aziendale è abilitato). Non supporta scenari che consentono solo il riutilizzo di oggetti senza la creazione di nuovi oggetti.

Per generare un'API, segui questi passaggi:

1. Fai clic sulla bacchetta magica nel menu di navigazione a sinistra per utilizzare Gemini Code Assist al fine di creare una nuova specifica dell'API. Assicurati di utilizzare questo metodo per creare le specifiche dell'API anziché la chat di Gemini Code Assist, che non supporta tutte le funzionalità e le funzionalità quando crei le specifiche dell'API.
   
2. Inserisci un prompt che descriva la nuova API nella finestra di immissione Crea una specifica API.
   1. Se vuoi, seleziona un modello di prompt dai chip di modello mostrati. Un modello di prompt fornisce un framework per il tuo prompt per aiutarti a iniziare.
   2. Inserisci un prompt. Consulta Come scrivere prompt efficaci per le specifiche delle API.
      
      
3. Gemini Code Assist genera una OAS che definisce l'API.
4. Esamina le specifiche:
   1. Fai clic su Visualizza codice per esaminare le specifiche nell'editor di codice.
   2. Il riquadro del renderer dell'API mostra l'anteprima dell'API perché può essere visualizzata dagli sviluppatori, inclusa la descrizione dell'API e altra documentazione.
   3. Se hai già delle API nell'hub API, questo contesto aziendale viene utilizzato per riutilizzare gli oggetti di altre API in questo OAS ed è elencato nel riquadro OUTPUT:
      
   4. Ti ringraziamo per il tuo feedback. Fornisci un feedback sulla specifica generata facendo clic sull'icona Mi piace o Non mi piace nel riquadro Swagger.
      
   5. Se vuoi modificare i prompt di anteprima e rigenerare la specifica, fai clic sulle frecce della cronologia dei prompt sopra i prompt per spostarti tra le richieste precedenti.
      
5. Testa le specifiche. Una volta completate le nuove specifiche, puoi testarle utilizzando un server fittizio. Consulta Testare l'API utilizzando un server fittizio.
6. Fai clic su Salva per salvare la nuova API con un nome a tua scelta.
7. Per creare un proxy API Apigee da questa specifica, fai clic su Crea proxy API dal menu Altro. Il processo di creazione crea un pacchetto proxy. Dovresti vedere il nuovo proxy nell'elenco dei tuoi proxy nel menu a sinistra. Per saperne di più sulla creazione di proxy da Cloud Code, consulta la procedura dettagliata per la creazione di proxy API integrato in Cloud Code.
   

Come scrivere prompt efficaci per le specifiche dell'API

L'accuratezza e l'idoneità della specifica di un'API generata dipendono in gran parte dal prompt fornito al modello.

Ecco alcuni esempi di prompt validi:

• Crea un'API che consenta ai clienti di pagare un ordine utilizzando vari metodi di pagamento come carte di credito e carte di debito.
• Accettare ordini di acquisto per l'acquisto di chicchi di caffè specializzati tramite un'API.
• Siamo una pizzeria e vogliamo creare una soluzione di consegna di pizze a domicilio personalizzata online. Crea un'API per accettare gli ordini di pizza.
• API per le attività di consegna di cibo a domicilio. I clienti possono ordinare una combinazione di pizza, hamburger o panini in un unico ordine. Ognuno di questi tipi di alimenti ha il proprio schema. Le pizze hanno i condimenti e le dimensioni. Gli hamburger includono condimenti e tipo di tortino. I sandwich includono tipo di pane, tipo di carne, verdure, formaggio e istruzioni personalizzate.

Questi esempi mostrano prompt meno efficaci. Cerca di evitare prompt strutturati in questo modo:

• Crea un'API per il mio negozio. Questo prompt contiene troppe poche informazioni affinché il modello possa generare una specifica completa e accurata.
• Crea una nuova API di rimborso che riutilizza l'oggetto ordine. Non è necessario specificare quali oggetti Gemini Code Assist deve riutilizzare durante la creazione di nuove API; Gemini Code Assist rileva automaticamente gli oggetti più adatti da riutilizzare.

Registra l'API con l'hub API

Una volta che l'API è stata esaminata e definitiva, puoi renderla disponibile agli sviluppatori registrandola con l'hub API:

1. Fai clic su Registrati all'hub API.
2. Segui le istruzioni per registrare l'API. Consulta la pagina Registrazione delle API per informazioni sulla registrazione con l'hub API e per le informazioni da fornire.

Aggiorna le API dell'hub API da Cloud Code

Puoi salvare una nuova versione delle specifiche dell'hub API quando le modifichi da Cloud Code.

Per salvare la specifica come nuova versione, fai clic sul pulsante Altre opzioni... nel riquadro Swagger e su Pubblica nell'hub API. Fornisci il nuovo ID versione API. Dovresti vedere la nuova versione nell'elenco delle versioni dell'API nell'elenco hub API in Cloud Code.

Utilizzare il file delle impostazioni per controllare i comportamenti di Gemini Code Assist

Questa sezione spiega come gestire se e come Gemini Code Assist è disponibile, dal file delle impostazioni.

Disabilita o abilita Gemini Code Assist

Dopo aver configurato Apigee in Cloud Code (consulta Configurare Apigee in Cloud Code), puoi aggiungere questa riga al file delle impostazioni per disabilitare temporaneamente tutte le funzionalità di Gemini Code Assist:

"cloudcode.apigee.gemini.enable": false

Rimuovi la riga o impostala su true (valore predefinito) per riattivare Gemini Code Assist.

Controlla il contesto aziendale nella generazione delle specifiche

La generazione di OAS può includere schema, metadati e definizioni di sicurezza da altre API dell'organizzazione. Il processo trova API simili utilizzando i nomi e le descrizioni degli oggetti nel catalogo dell'hub API presenti nel catalogo dell'hub API a cui hai l'autorizzazione ad accedere. Lo stato di deployment delle API dell'hub API non viene considerato.

Il contesto aziendale è abilitato per impostazione predefinita.

Puoi:

• Controlla il numero di modifiche incluse dal contesto aziendale, se presenti, nel riquadro Swagger:
• Visualizza le modifiche incluse nel riquadro Output:

Per disabilitare il contesto aziendale per la nuova generazione di 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 suo complesso. Imposta su false per disattivare il contesto aziendale.
• includeMetadata consente di stabilire se includere o meno il contesto dei metadati. Questa impostazione include o esclude i metadati di altre API nell'hub API. includeMetadata è applicabile solo quando enabled è impostato su true.
• includeSchema determina se è incluso il contesto dello schema. Questa impostazione include o esclude le informazioni sullo schema di altre API nell'hub API. includeSchema è applicabile solo quando enabled è impostato su true.
• includeSecurity consente di stabilire se includere o meno 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.

Modifica API

Per utilizzare Cloud Code per modificare le API esistenti che fanno parte del catalogo dell'hub API, segui queste istruzioni. Le modifiche apportate in Cloud Code possono essere salvate nell'hub API.

Queste istruzioni sono destinate agli utenti che non utilizzano il componente aggiuntivo Gemini Code Assist per Apigee. Per informazioni sulle funzionalità aggiuntive disponibili con Gemini Code Assist durante la progettazione e la modifica delle API, consulta Progettare un'API con Gemini Code Assist.

Nota: al momento, eventuali modifiche all'API salvate nell'hub API devono essere salvate come una nuova versione.

Per modificare una specifica dell'API:

1. Assicurati che il progetto selezionato in Cloud Code sia quello con il catalogo dell'hub API contenente l'API da modificare.
2. Nel menu di navigazione a sinistra, espandi la struttura dell'hub API.
3. Seleziona dall'elenco l'API e la versione da modificare.
4. Modifica la specifica nel riquadro di modifica. Puoi anche visualizzare le operazioni dell'API nel riquadro Swagger.
5. Facoltativamente, testa l'API utilizzando un server fittizio.
6. Salva le modifiche come nuova versione con il pulsante Altro nel riquadro Swagger, quindi Pubblica nell'hub API. Conferma o aggiorna la versione quando richiesto e salva le modifiche nell'hub API. Dovresti vedere la nuova versione nell'elenco delle versioni dell'API nell'elenco hub API in Cloud Code.

Testa l'API utilizzando un server fittizio

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

Utilizza il server fittizio locale

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

Nota: il server fittizio locale potrebbe non funzionare correttamente quando utilizzi VS Code Remote Explorer. Inoltre, a volte il server fittizio locale non può essere avviato. In tal caso, non sarà disponibile nell'elenco a discesa.

Per utilizzare il server fittizio locale:

1. Seleziona il server fittizio locale (server di sviluppo) dall'elenco a discesa Server.
   
2. Apri un percorso e fai clic su Prova.
   
3. Compila i parametri della richiesta e fai clic su Esegui.
   
4. Puoi anche inviare richieste utilizzando curl da un prompt. Utilizza l'indirizzo e la porta del server dal menu a discesa Server.

Usa un server simulato remoto

Un server fittizio remoto consente di creare un'istanza del server fittizia permanente che, a differenza del server fittizio locale, può essere condivisa e utilizzata da altri utenti all'interno della tua organizzazione per testare la nuova API prima che sia in produzione. I server fittizi remoti possono essere utilizzati solo con le API registrate nell'hub API.

Al momento è possibile creare server fittizi remoti in Google Cloud. I server fittizi remoti di Google Cloud non si aggiornano automaticamente per le eventuali modifiche apportate all'API dopo il deployment del server fittizio, quindi attendi di aggiungere il server fittizio finché non hai creato completamente l'API.

Il deployment di un server simulato remoto di Google Cloud crea un nuovo servizio Cloud Run. Crea un'immagine container per il server fittizio utilizzando Cloud Build e carica l'immagine container in Cloud Artifact Registry nel tuo progetto Google. Sei responsabile degli eventuali costi risultanti e della manutenzione di questi ultimi dopo la creazione. È inoltre tua responsabilità eliminarli una volta che non sono più necessari. Vedi Che cos'è Cloud Run?, Gestione dei servizi e la documentazione di Artifact Registry.

Importante: dopo aver creato un server fittizio remoto di Google Cloud, sei responsabile degli eventuali costi derivanti dall'utilizzo, dalla sua gestione e dalla sua rimozione quando non è più necessario. Per informazioni sui prezzi, incluse informazioni su eventuali opzioni del Livello gratuito, visita la pagina https://cloud.google.com/run/pricing.

Per eseguire il deployment di un server fittizio remoto:

1. Seleziona Esegui il deployment del server fittizio (Google Cloud) dal menu Altro.
2. Se l'API non è già registrata nell'hub API, registrala quando richiesto.
3. Specifica i dettagli del server fittizio remoto: ID progetto, Nome server e Regione, quindi fai clic su Crea per creare il server fittizio remoto.
   Importante: non creare più server fittizi remoti con lo stesso nome, anche se l'interfaccia utente non ti impedisce al momento di farlo.
4. La generazione del server fittizio remoto richiede diversi minuti. Puoi osservare l'avanzamento nel riquadro OUTPUT di Google Cloud.
5. Una volta completata la creazione del server fittizio remoto, vedrai l'URL del server remoto nell'elenco dei server del riquadro Swagger e nel riquadro OUTPUT.
6. Per utilizzare il server fittizio, apri un percorso e fai clic su Prova.
   
   
   Compila i parametri della richiesta e fai clic su Esegui.
   
   
   Puoi anche inviare richieste da un prompt utilizzando curl. Utilizza l'indirizzo e la porta del server dal menu a discesa Server.

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

1. Assegna ad altri utenti il ruolo richiamar per il servizio di cui è stato eseguito il deployment. Vedi Autenticare gli sviluppatori.
2. Quando effettuano la richiesta al server fittizio, gli utenti seguono le istruzioni in Testare il servizio privato.

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

1. Vai all'hub API e trova l'API per visualizzare tutti i deployment per l'API, inclusi eventuali server fittizi remoti.
2. Utilizza l'URL risorsa per accedere al deployment e gestirlo mediante l'arresto, l'eliminazione e l'esecuzione di altre azioni sul server fittizio.