Consulta i connettori supportati per Application Integration.

Visualizza la specifica OpenAPI per l'integrazione

Anteprima - OpenAPI Specification

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.

L'Application Integration consente di generare e visualizzare dinamicamente le specifiche OpenAPI delle integrazioni pubblicate configurate con uno o più attivatori API. L'accesso alla specifica OpenAPI dell'integrazione ti consente di:

• Ottieni una comprensione completa degli endpoint, dei metodi e delle strutture di dati dell'API dell'integrazione.
• Consenti uno sviluppo e una risoluzione dei problemi più efficienti fornendo una visualizzazione dettagliata e centralizzata dell'API della tua integrazione.
• Esponi le tue API di integrazione e integrale perfettamente con gli agenti di conversazione, come gli agenti di conversazione di Google Cloud.

Che cos'è la specifica OpenAPI?

La specifica OpenAPI (OAS) è un formato standard indipendente dal linguaggio per descrivere le API RESTful. Generalmente scritta nei formati YAML o JSON, la specifica OpenAPI presenta una descrizione formale degli elementi dell'API, come l'URL base, i percorsi e i verbi, le intestazioni, parametri di ricerca, i tipi di contenuti, i modelli di richiesta e risposta e altro ancora. Per ulteriori informazioni sulla specifica OpenAPI, consulta la specifica OpenAPI.

Nota: l'Application Integration supporta solo la versione 3.0.1 della specifica OpenAPI.

Generare e visualizzare la specifica OpenAPI

Puoi generare e visualizzare dinamicamente la specifica OpenAPI per le tue integrazioni dall'editor di integrazione nella console Google Cloud o utilizzando una chiamata API.

Prima di iniziare

• Verifica che l'integrazione sia configurata con uno o più attivatori API. Per informazioni sulla configurazione degli trigger API, consulta Trigger API.
• Pubblica l'integrazione. Per informazioni su come pubblicare un'integrazione, vedi Testare e pubblicare le integrazioni.

Visualizza la specifica OpenAPI

Per visualizzare la specifica OpenAPI per l'integrazione, seleziona una delle opzioni:

Console

Per visualizzare la specifica OpenAPI per un'integrazione specifica:

1. Vai alla pagina Integrazione applicazioni.

   Vai ad Application Integration

2. Nel menu di navigazione, fai clic su Integrations (Integrazioni).

   Viene visualizzata la pagina Integrazioni, che elenca tutte le integrazioni disponibili nel progetto Google Cloud .

3. Fai clic sull'integrazione per cui vuoi visualizzare la specifica OpenAPI. Viene visualizzata l'integrazione nell'editor integrazioni.
4. Fai clic su (menu Azioni) nella barra degli strumenti dell'editor di integrazione e seleziona Visualizza specifica OpenAPI.

   Viene visualizzato il riquadro Visualizza specifica OpenAPI che mostra la specifica OpenAPI dell'integrazione. Per impostazione predefinita, la specifica OpenAPI generata contiene tutti gli attivatori API configurati nell'integrazione.

   • Per visualizzare la specifica OpenAPI per un attivatore API specifico, seleziona l'attivatore API dall'elenco a discesa API.
   • Per scaricare la specifica OpenAPI come file YAML, fai clic su scarica (Scarica).

Nota: dall'editor di integrazione puoi visualizzare e scaricare la specifica OpenAPI, in formato YAML, per una sola integrazione alla volta. Per visualizzare e scaricare la specifica OpenAPI nei formati YAML o JSON, segui le istruzioni riportate nella sezione API.

API

Il metodo generateOpenApiSpec dell'API Application Integration ti consente di visualizzare la specifica OpenAPI per l'integrazione utilizzando una chiamata API.

Utilizza il seguente comando curl per visualizzare la specifica OpenAPI per una o più integrazioni nella stessa regione:

Suggerimento: curl in genere è preinstallato per i sistemi operativi Linux e macOS. Se non hai curl, puoi scaricarlo dalla pagina delle release e dei download di curl.

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/integrations/-:generateOpenApiSpec"
          

Sostituisci quanto segue:

• TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: i nomi dell'attivatore API nell'integrazione per cui vuoi visualizzare la specifica OpenAPI.
• INTEGRATION_NAME: il nome dell'integrazione.
• DOC_TYPE: il tipo di documento da generare. Sono supportati i seguenti valori: YAML o JSON.
• PROJECT_ID: l'ID del tuo progetto Google Cloud .
• LOCATION: la posizione del tuo progetto Google Cloud .
  Nota: puoi visualizzare la specifica OpenAPI solo per più integrazioni nella stessa regione.

Informazioni sulla specifica OpenAPI

L'Application Integration genera la specifica OpenAPI per le integrazioni pubblicate in base allo standard OpenAPI Specification 3.0. La tabella seguente descrive gli elementi della specifica OpenAPI generata in Application Integration:

Elemento	Descrizione
openapi	La versione della specifica OpenAPI utilizzata.
info	Informazioni sull'integrazione, ad esempio il nome (titolo), la descrizione e la versione pubblicata.
servers	Gli URL dei server che ospitano l'integrazione.
paths	I percorsi vengono creati per ogni attivatore API selezionato nell'integrazione. L'URL del server combinato con il percorso costituisce l'endpoint API per effettuare chiamate API. I campi Request e Response vengono compilati in base alle variabili di input e output configurate per l'attivatore API corrispondente. Nota: l'Application Integration supporta attualmente solo un insieme limitato di parole chiave dello schema JSON. Per informazioni sulle parole chiave supportate, consulta la sezione Considerazioni.
components	Il campo schemas contiene lo schema JSON per le variabili di input e output dell'attivatore dell'API. Il campo securitySchemes contiene le informazioni di autenticazione per gli attivatori dell'API.

Considerazioni

Quando visualizzi la specifica OpenAPI per l'integrazione, tieni presenti le seguenti considerazioni:

• La specifica OpenAPI viene generata solo per le integrazioni pubblicate.
• La specifica OpenAPI viene generata solo per le integrazioni configurate con uno o più attivatori API.
• La specifica OpenAPI viene generata solo per le integrazioni nella stessa regione.
• La specifica OpenAPI viene generata in formato YAML per impostazione predefinita. Per generare e visualizzare la specifica OpenAPI in formato JSON, imposta il parametro fileFormat su JSON nella chiamata API.
• L'Application Integration attualmente supporta solo il seguente insieme limitato di parole chiave dello schema JSON:
  • type
  • items
  • properties
  • description
  • required
  • array
  • object
  • oneOf
  • allOf
  • anyOf
  • not
  • null
  • enum
  • additionalProperties
  • default
• Quando convalidi la specifica OpenAPI utilizzando Swagger Editor, potresti riscontrare errori semantici relativi ai percorsi dell'API simili a quelli dell'immagine seguente:

  

  Questi errori possono essere ignorati. La specifica OpenAPI è ancora valida.