Progettazione e modifica di API

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza 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 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 scenari per il solo riutilizzo senza crearne di nuovi.

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 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, ad esempio Descrizione dell'API e altra documentazione.
   3. Se hai già delle API nell'hub API, quel contesto aziendale viene utilizzato riutilizzano oggetti di altre API in questo OAS ed è enumerato 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 le specifiche, fai clic sulle frecce della cronologia dei prompt sopra i prompt per passare da una richiesta all'altra.
      
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 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 proxy bundle. Dovresti vedere il nuovo proxy nell'elenco dei tuoi proxy nel menu a sinistra. Visualizza il proxy API procedura dettagliata di creazione integrata in Cloud Code per ulteriori informazioni creando proxy da Cloud Code.
   

Come scrivere prompt efficaci per le specifiche delle 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 validi:

• Creare un'API che consenta ai clienti di pagare un ordine utilizzando diversi 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 pizza a domicilio personalizzata online soluzione. 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 condimenti e dimensioni. Gli hamburger includono condimenti e tipo di tortino. I panini includono tipo di pane, carne tipo, 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 per consentire al modello per 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 Registra le API per le informazioni sulla registrazione all'hub API e 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 su il pulsante Altre opzioni... nel riquadro Swagger e Pubblica nell'hub API. Fornire 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, dalla del file di impostazioni.

Disabilita o abilita 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 (valore predefinito) per riattivarla Gemini Code Assist.

Controlla 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 nell'hub API catalogo presente nel catalogo dell'hub API a cui disponi dell'autorizzazione ad accedere. Lo stato del deployment delle API dell'hub API non viene considerata.

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 è attivate 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 è solo applicabile quando il valore di enabled è impostato su true.
• includeSchema determina se è incluso il contesto dello schema. Questa impostazione Include o esclude le informazioni sullo schema da 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. 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 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 API, vedi Progettare un'API con Gemini Code Assist.

Nota: al momento, eventuali modifiche all'API sono state salvate nell'hub API deve essere salvato come 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 in Swagger dal riquadro.
5. Facoltativamente, testa l'API utilizzando un server fittizio.
6. Salva le modifiche come nuove version con Altro nel riquadro Swagger e poi Pubblica nell'hub API. Conferma o aggiorna la versione quando richiesto e salva le modifiche all'hub API. La nuova versione dovrebbe comparire nella versione per quell'API nell'elenco dell'hub API in Cloud Code.

Testa l'API utilizzando un server fittizio

Puoi testare l'API utilizzando un server fittizio locale o una simulazione remota basata su Google Cloud o server web. 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 fittizio locale accetta 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 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 questo 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 il server indirizzo e porta 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 con e utilizzata da altri all'interno della tua organizzazione per testare la nuova API prima che sia in e 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. Google I server fittizi remoti di Cloud non si aggiornano automaticamente eseguire il deployment nell'API dopo aver eseguito il deployment del server fittizio, quindi attendi di aggiungerlo hanno creato completamente l'API.

Il deployment di un server simulato remoto di Google Cloud crea un nuovo servizio Cloud Run. Sviluppa per il server fittizio utilizzando Cloud Build e carica l'immagine container in Cloud Artifact Registry nel tuo progetto Google; sei responsabile e la manutenzione di quelli dopo la creazione. Inoltre responsabile di eliminarle una volta che non sono più necessarie. Consulta Che cos'è Cloud Run?, Gestione dei servizi e 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ù. Consulta https://cloud.google.com/run/pricing per informazioni sui prezzi, incluse informazioni su eventuali opzioni del Livello gratuito.

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 e 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 impedirà di farlo in questo momento.
4. La generazione del server fittizio 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 i parametri della 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 fittizio con altri utenti:

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

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

1. Vai all'hub API e individua 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.