Progettazione e modifica delle API

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

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

Ruoli aggiuntivi necessari per la progettazione di API

Per eseguire alcuni passaggi di progettazione e test dell'API descritti in questa pagina, sono necessari i ruoli elencati di seguito.

Attività	Ruoli richiesti
Progettare le API utilizzando Gemini Code Assist	Utente di Gemini for Google Cloud Consumatore di utilizzo del servizio Vedi Concedi i ruoli IAM in un progetto Google Cloud per Gemini Code Assist.
Utilizza il contesto aziendale delle tue API esistenti nell'hub API quando progetti le API	Visualizzatore di Cloud API Hub
Registra le nuove API in API Hub	Editor o amministratore di Cloud API Hub
Modificare le API hub in Cloud Code	Editor o amministratore di Cloud API Hub
Configura e gestisci un server simulato remoto per testare le API	Amministratore del registry di elementi Account di servizio Cloud Build Amministratore di Cloud Run Amministratore dell'utilizzo dei servizi Consulta la documentazione di riferimento sui ruoli IAM di base e predefiniti.

Progettare 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 con specifica OpenAPI (OAS), versione 3.0 utilizzando l'Assistente codice Gemini. Gemini Code Assist può includere il contesto aziendale per l'assistenza dell'AI generativa nel processo di sviluppo dell'API. Il contesto aziendale utilizza le API hub API del progetto per il contesto quando genera nuove API ed è disponibile solo con i progetti che utilizzano l'hub API.

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

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 per il riutilizzo di oggetti senza creare nuovi oggetti.

Generare un'API

Per generare un'API:

1. Fai clic sulla bacchetta magica nel riquadro di navigazione a sinistra per utilizzare Gemini Code Assist per creare una nuova specifica API. Assicurati di utilizzare questo metodo per creare specifiche API anziché la chat di Gemini Code Assist, che non supporta tutte le funzionalità e le funzionalità durante la creazione di specifiche 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 visualizzati. Un modello di prompt fornisce un framework per il prompt per aiutarti a iniziare.
   2. Inserisci una richiesta. Consulta Come scrivere prompt efficaci per le specifiche dell'API.
      
      
3. Gemini Code Assist genera un file OAS che definisce l'API.
4. Esamina le specifiche:
   1. Fai clic su Visualizza codice per esaminare la specifica nell'editor di codice.
   2. Il riquadro del visualizzatore dell'API mostra l'anteprima dell'API così come può essere visualizzata dagli sviluppatori, inclusa la descrizione dell'API e altra documentazione.
   3. Se hai già API nell'hub API, questo contesto aziendale viene utilizzato per riutilizzare gli oggetti di altre API in questa 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 i prompt precedenti.
      
5. Testa la specifica. Una volta completata la nuova specifica, puoi testarla utilizzando un server simulato. Consulta Testare l'API utilizzando un server simulato.
6. Fai clic su Salva per salvare la nuova API assegnandole 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 genera un bundle di proxy. Dovresti vedere il nuovo proxy nell'elenco dei proxy del menu a sinistra. Per ulteriori informazioni sulla creazione di proxy da Cloud Code, consulta la procedura dettagliata per la creazione di proxy API integrata in Cloud Code.
   

Come scrivere prompt efficaci per le specifiche API

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

Ecco alcuni esempi di prompt buoni:

• Crea un'API che consenta ai clienti di pagare un ordine utilizzando vari metodi di pagamento, come carte di credito e di debito.
• Accettare ordini di acquisto di chicchi di caffè speciali tramite un'API.
• Siamo una pizzeria e vogliamo creare una soluzione online per la consegna di pizza personalizzata. Crea un'API per accettare gli ordini di pizza.
• 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 includono il tipo di pane, il tipo di carne, le verdure, il formaggio e le istruzioni personalizzate.

Questi esempi mostrano prompt meno efficaci. Cerca di evitare prompt strutturati come questi:

• Creare un'API per il mio negozio. Questo prompt contiene informazioni troppo poche per consentire al modello di generare una specifica completa e accurata.
• Crea una nuova API di rimborso che riutilizzi l'oggetto ordine. Non è necessario specificare quali oggetti deve riutilizzare Gemini Code Assist quando crei 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 completata, puoi renderla disponibile per gli sviluppatori registrandola con l'hub API:

1. Fai clic su Registrati all'hub API.
2. Segui le istruzioni per registrare l'API. Consulta Registrare le API per informazioni su come registrarti all'hub API e sulle informazioni da fornire.

Aggiornare 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 poi su Pubblica nell'hub API. Fornisci l'ID della nuova versione dell'API. La nuova versione dovrebbe essere visualizzata nell'elenco delle versioni per l'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.

Disattivare o attivare 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 disattivare temporaneamente tutte le funzionalità di Gemini Code Assist:

"cloudcode.apigee.gemini.enable": false

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

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 nel catalogo dell'hub API a cui hai l'autorizzazione di accesso. Lo stato di implementazione delle API hub API non viene preso in considerazione.

Il contesto aziendale è abilitato per impostazione predefinita.

Puoi:

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

Per disattivare il contesto aziendale per la generazione di nuove specifiche, aggiungi queste righe al settings.json file 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.

Modificare le API

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

Queste istruzioni sono rivolte 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, qualsiasi modifica all'API salvata nell'hub API deve essere salvata come nuova versione.

Per modificare una specifica API:

1. Assicurati che il progetto selezionato in Cloud Code sia il progetto con il catalogo dell'hub API contenente l'API che vuoi modificare.
2. Nel riquadro di navigazione a sinistra, espandi l'albero API Hub.
3. Seleziona l'API e la versione da modificare dall'elenco.
4. Modifica la specifica nel riquadro di modifica. Puoi anche visualizzare le operazioni API nel pannello Swagger.
5. Se vuoi, puoi testare l'API utilizzando un server simulato.
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 nuovamente le modifiche nell'hub API. La nuova versione dovrebbe essere visualizzata nell'elenco delle versioni per l'API nell'elenco Hub API in Cloud Code.

Testare l'API utilizzando un server simulato

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

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.

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

Per utilizzare il server simulato locale:

1. Seleziona il server simulato locale (server di sviluppo) nel menu a discesa Server.
   
2. Apri un percorso e fai clic su Prova.
   
3. Compila eventuali parametri di 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.

Utilizzare un server simulato remoto

Un server simulato remoto ti 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 prima che venga messa in produzione. I server simulati remoti possono essere utilizzati solo con le API registrate nell'hub API.

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

Il deployment di un server simulato remoto Google Cloud 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. Sei responsabile di eventuali costi e della manutenzione delle risorse dopo la creazione. Sei inoltre responsabile dell'eliminazione quando non sono più necessari. Consulta Che cos'è Cloud Run?, Gestire i servizi e la documentazione di Artifact Registry.

Importante: dopo aver creato un server simulato remoto Google Cloud, sei responsabile di eventuali costi derivanti dal suo utilizzo, dalla sua gestione e dalla sua rimozione quando non è più necessario. Visita https://cloud.google.com/run/pricing per informazioni sui prezzi, incluse quelle su eventuali opzioni del livello gratuito.

Per eseguire il deployment di un server simulato remoto:

1. Seleziona Esegui il deployment del server simulato (Google Cloud) dal menu Altro.
2. Se la tua API non è ancora registrata in API Hub, registrala quando richiesto.
3. Specifica i dettagli del server simulato remoto: ID progetto, Nome server e Regione e 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.
4. La generazione del server simulato remoto richiede diversi minuti. Puoi monitorare l'avanzamento nel pannello OUTPUT di Google Cloud.
5. Al termine della creazione del server simulato remoto, vedrai l'URL del server remoto nell'elenco dei server del riquadro Swagger e nel riquadro OUTPUT.
6. 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:

1. Assegna ad altri utenti il ruolo di invocatore per il servizio di cui è stato eseguito il deployment. Consulta Autenticare gli sviluppatori.
2. 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:

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