Consulta i connettori supportati per Application Integration.

Visualizzare la specifica OpenAPI per l'integrazione

Application Integration offre la possibilità di generare e visualizzare dinamicamente le specifiche OpenAPI delle integrazioni pubblicate configurate con uno o più trigger API. L'accesso alla specifica OpenAPI della tua integrazione ti consente di:

  • Acquisisci una comprensione completa degli endpoint, dei metodi e delle strutture di dati dell'API della tua integrazione.
  • Consente uno sviluppo e una risoluzione dei problemi più efficienti fornendo una visualizzazione dettagliata e centralizzata dell'API della tua integrazione.
  • Esporre le API di integrazione e integrarsi perfettamente con gli agenti conversazionali. Consulta Creare agenti conversazionali con Application Integration.

Che cos'è la specifica OpenAPI?

Logo della specifica OpenAPI

La specifica OpenAPI (OAS) è un formato standard e indipendente dalla lingua per descrivere le API RESTful. Scritta comunemente in formato YAML o JSON, la specifica OpenAPI presenta una descrizione formale degli elementi dell'API, come l'URL di 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 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ù trigger API. Per informazioni sulla configurazione dei 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 Application Integration.

    Vai ad Application Integration

  2. Nel menu di navigazione, fai clic su 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. Si apre 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 i trigger API configurati nell'integrazione.

    • Per visualizzare la specifica OpenAPI per un trigger API specifico, selezionalo dall'elenco a discesa API.
    • Per scaricare la specifica OpenAPI come file YAML, fai clic su download (Scarica).

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:

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:generateOpenApiSpec"

Sostituisci quanto segue:

  • TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: i nomi del trigger 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 Google Cloud progetto.
  • LOCATION: la posizione del tuo progetto Google Cloud .

Comprendere la specifica OpenAPI

Application Integration genera la specifica OpenAPI per le integrazioni pubblicate seguendo lo standard OpenAPI Specification 3.0. La tabella seguente descrive gli elementi della specifica OpenAPI generati in Application Integration:

Elemento Descrizione
openapi La versione della specifica OpenAPI utilizzata.
info Informazioni sull'integrazione, ad esempio nome (titolo), descrizione e versione pubblicata.
servers Gli URL del server che ospitano l'integrazione.
paths I percorsi vengono creati per ogni trigger 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 il trigger API corrispondente.

components Il campo schemas contiene lo schema JSON per le variabili di input e output del trigger API.

Il campo securitySchemes contiene le informazioni di autenticazione per i trigger API.

Considerazioni

Quando visualizzi la specifica OpenAPI per la tua integrazione, tieni presente 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ù trigger 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.
  • 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 l'editor Swagger, potresti riscontrare errori semantici relativi ai percorsi API simili all'immagine seguente:

    Swagger Editor Swagger Editor

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

Passaggi successivi