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	Gemini per l'utente Google Cloud Consumer utilizzo dei servizi Consulta: Concedi ruoli IAM in un progetto Google Cloud per Gemini Code Assist.
Usa il contesto aziendale delle API esistenti nell'hub API quando progettazione di API	Visualizzatore dell'hub API Cloud
Registra le nuove API in API Hub	Editor o amministratore dell'hub API Cloud
Modificare le API hub in Cloud Code	Editor o amministratore di Cloud API Hub
Imposta e gestisci un server fittizio 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 usare Cloud Code per progettare Specifica OpenAPI (OAS), versione 3.0 che utilizzano Gemini Code Assist. Gemini Code Assist può includere un contesto aziendale per AI generativa assistenza nel processo di sviluppo delle API. Il contesto aziendale utilizza le API dell'hub API del progetto per 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 (se il contesto aziendale è abilitato). Non supporta gli scenari per il riutilizzo degli oggetti senza creare nuovi oggetti.

Generare un'API

Per generare un'API, segui questi passaggi:

1. Fai clic sulla bacchetta magica nel menu di navigazione a sinistra per utilizzare Gemini Code Assist e creare una nuova specifica API. Marca assicurati di utilizzare questo metodo per creare specifiche delle API invece della chat di Gemini Code Assist, non supporta tutte le caratteristiche e le funzionalità durante la creazione delle 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 una richiesta. Consulta Come scrivere prompt efficaci per le specifiche dell'API.
      
      
3. Gemini Code Assist genera una 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 renderer dell'API mostra l'anteprima dell'API perché può essere visualizzata dagli sviluppatori, ad esempio 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 sulle specifiche generate facendo clic sul 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 le specifiche. Quando le nuove specifiche sono complete, puoi testarle utilizzando un server fittizio. Consulta: Testa l'API utilizzando un server fittizio.
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 proxy bundle. 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 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 per l'acquisto di chicchi di caffè specializzati 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:

• 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 una nuova API di rimborso che riutilizza l'oggetto ordine. Non è necessario specificare quali oggetti Gemini Code Assist dovrebbe riutilizzare durante la creazione di nuove API. Assistente codice Gemini 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 Registrare le API per informazioni su come registrarti all'hub API e sulle 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 su il pulsante Altre opzioni... nel riquadro Swagger e Pubblica nell'hub API. Fornisci il nuovo ID versione API. La nuova versione dovrebbe comparire nella versione per quell'API nell'elenco dell'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

Una volta configurata Apigee in Cloud Code (vedi Configurazione di Apigee in Cloud Code), puoi aggiungere questa riga al file delle impostazioni per disattivare temporaneamente tutti i servizi di Gemini Code Assist caratteristiche:

"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 del altre API. 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:

• Vedi il numero di modifiche incluse dal contesto aziendale, se presenti, nella Riquadro spavaldo:
• Visualizza le modifiche incluse nel riquadro Output:

Per disabilitare il contesto aziendale per la nuova generazione di specifiche, aggiungi queste righe nella 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 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 controlla se il contesto dello schema è incluso. Questa impostazione Include o esclude le informazioni sullo schema da altre API nell'hub API. includeSchema è applicabile solo quando enabled è impostato su true.
• includeSecurity controlla se è incluso il contesto relativo alla sicurezza. Questo l'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 del tuo 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 su funzionalità aggiuntive disponibili con Gemini Code Assist durante la progettazione e la modifica per le API, vedi 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 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 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 comparire nella versione per quell'API nell'elenco dell'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 fittizio locale è installato e disponibile per impostazione predefinita mentre è necessario configurare e gestire server fittizi di Google Cloud.

Utilizza il server fittizio 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 non sarà disponibile nell'elenco a discesa.

Per utilizzare il server fittizio 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 i parametri della richiesta e fai clic su Esegui.
   
4. Puoi anche inviare richieste utilizzando curl da un prompt. Utilizza il server indirizzo e porta 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 in API Hub.

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 risultanti 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 fittizio remoto di Google Cloud l'utente è responsabile di tutti i costi derivanti dall'utilizzo, dalla sua gestione e dalla sua rimozione, non serve più. 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 fittizio (Google Cloud) dal menu Altro.
2. Se la tua API non è ancora registrata nell'hub API, 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 seguire l'avanzamento in nel riquadro OUTPUT di Google Cloud.
5. Una volta completata la creazione del server fittizio remoto, visualizzerai l'URL del server remoto nella Elenco dei server del riquadro Swagger e riquadro OUTPUT.
6. Per utilizzare il server fittizio, 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 il server indirizzo e porta 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: Autentica 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 deployment per l'API, inclusi eventuali deployment server fittizi remoti.
2. Utilizza l'URL della risorsa per accedere al deployment e gestirlo mediante interruzione, eliminazione e l'esecuzione di altre azioni sul server fittizio.