Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
# Integrazione delle specifiche OpenAPI
Con l'integrazione con OpenAPI Specification, puoi creare integrazioni personalizzate basate su schemi OpenAPI. Ciò consente di connettersi a qualsiasi API che fornisca una specifica OpenAPI. Per i requisiti di abbonamento ad Amazon Quick, consulta[Configura le integrazioni nella console](integration-console-setup-process.md).
## Cosa puoi fare
L'integrazione delle specifiche OpenAPI fornisce una connettività basata su schemi per aiutarti a lavorare con API personalizzate.
**Connettore Action**
Esegui azioni basate sulle specifiche di OpenAPI. Esegui chiamate API, gestisci risorse e interagisci con servizi personalizzati tramite azioni generate dinamicamente in base allo schema fornito.
**Schema-based configurazione**
Importa le specifiche OpenAPI per generare automaticamente azioni e azioni disponibili. Support per la convalida dello schema JSON e la mappatura dei parametri.
## Prima di iniziare
Prima di configurare l'integrazione delle specifiche OpenAPI, assicurati di avere quanto segue:
+ Specificazione OpenAPI (versione 3.0.0 o successiva) per l'API di destinazione.
+ Credenziali di autenticazione API (chiave API, OAuth o altro).
+ Amazon Quick Author o versione successiva.
+ Documentazione API e accesso agli endpoint.
## Preparare le specifiche e l'autenticazione OpenAPI
Prima di configurare l'integrazione in Amazon Quick, prepara le specifiche OpenAPI e le credenziali di autenticazione. Le specifiche OpenAPI devono soddisfare requisiti specifici per un'integrazione di successo.
### Requisiti di base
Le specifiche OpenAPI devono soddisfare questi requisiti di base.
+ **Versione OpenAPI**: è richiesta la versione 3.0.0 o successiva.
+ Formato di **file: solo in formato** JSON (). application/json
+ **Limite di dimensione del file**: massimo 1 MB per l'intera specifica OpenAPI.
+ **Limite operativo**: minimo 1 e massimo 100 operazioni API per connettore.
### Campi dello schema obbligatori
La tua specifica OpenAPI deve includere queste sezioni obbligatorie.
**openapi**
La versione OpenAPI utilizzata (deve essere «3.0.0" o superiore).
**Info**
Informazioni sul servizio tra cui titolo, descrizione e versione.
**server**
Informazioni di base su URL e server per la connettività API.
**percorsi**
definizioni degli endpoint API con metodi e operazioni HTTP.
### Schemi di autenticazione supportati
Prepara le credenziali di autenticazione in base ai metodi di autenticazione supportati nelle specifiche OpenAPI.
**OAuth 2.0**
Supporta sia i flussi Authorization Code Grant che Client Credentials Grant. Richiede AuthorizationUrl, tokenUrl e le definizioni degli ambiti nello schema di sicurezza.
**Chiave API**
L'autenticazione tramite chiave API viene passata nei parametri o nelle intestazioni della query.
**Nessuna autenticazione**
Opzione predefinita quando nella specifica non sono definiti schemi di sicurezza.
**Nota**
Gli schemi di autenticazione non supportati nella specifica OpenAPI verranno ignorati e per impostazione predefinita il connettore non utilizzerà alcuna autenticazione.
## Configurare l'integrazione delle specifiche OpenAPI
Dopo aver preparato la specifica OpenAPI e le credenziali di autenticazione, segui questi passaggi per creare l'integrazione della specifica OpenAPI.
1. Nella console Amazon Quick, scegli **Connettori**.
1. Scegli la scheda **Crea per il tuo team**.
1. Trova e scegli **OpenAPI** Specification.
1. Nella pagina Aggiungi schema, seleziona **Importa schema** e scegli uno schema da importare.
1. Seleziona **Avanti**.
1. Inserisci i dettagli dell'integrazione, inclusi nome e descrizione.
1. Esamina le azioni disponibili generate dalle tue specifiche OpenAPI.
1. Seleziona **Crea e continua**.
1. Scegli gli utenti con cui condividere l'integrazione.
1. Fare clic su **Avanti**.
### Risultato previsto
Dopo una corretta configurazione, l'integrazione della specifica OpenAPI viene visualizzata nell'elenco delle integrazioni con azioni generate dinamicamente in base allo schema. L'integrazione è disponibile per l'uso nei flussi di lavoro, nelle automazioni e negli agenti AI di Amazon Quick, con attività corrispondenti agli endpoint definiti nella specifica OpenAPI.
## Requisiti di formato e modello
Le specifiche OpenAPI devono rispettare questi requisiti di formato.
+ **Schemi di percorso**: devono seguire lo schema: `^/[^/]*(/[^/]*)*$` e iniziare con una barra (/).
+ **ID operativi**: devono seguire lo schema:`^[a-zA-Z0-9_ ]{1,256}$`.
+ **Descrizioni** - Obbligatorio per tutte le operazioni e i parametri, massimo 5000 caratteri.
+ **Tipo di contenuto**: application/json è supportato solo per i corpi di richiesta e risposta.
## Caratteristiche non supportate
Le seguenti funzionalità di OpenAPI non sono supportate e causeranno errori di convalida.
+ **Tipi di array**: gli schemi con tipi di array (ad esempio,`{"type": "array", "items": {"string"}}`) non sono supportati.
+ **Parole chiave di composizione**: allOf, OneOf, anyOf e not non sono supportate.
+ **Riferimenti circolari: i riferimenti** circolari o ciclici ($ref all'interno di $ref) non sono supportati.
+ Strutture **nidificate complesse: quando possibile, evitate strutture** di oggetti profondamente annidate.
## Le migliori pratiche relative allo schema
Segui queste best practice quando crei le tue specifiche OpenAPI.
### Scrivi descrizioni efficaci
Utilizza queste linee guida per scrivere descrizioni chiare e utili.
+ **Descrizioni delle operazioni**: descrivi cosa fa l'operazione, quando utilizzarla e come si comporta.
+ **Descrizioni dei parametri**: spiegano in modo conciso lo scopo del parametro e l'impatto sul comportamento operativo.
+ **Self-contained contenuto** - Assicurati che le descrizioni forniscano una guida sufficiente senza riferimenti esterni.
+ **Chiarezza delle dipendenze**: rendi esplicite le dipendenze tra le operazioni nelle descrizioni.
+ **Riferimenti operativi**: usa operationID quando fai riferimento ad altre operazioni, non ai percorsi API.
### Consigli sulla struttura dei parametri
Strutturate i parametri per un'usabilità ottimale.
+ **Appiattisci oggetti complessi: anziché oggetti** annidati, utilizza parametri separati (ad esempio, start\_date, start\_time, end\_date, end\_time).
+ **Utilizza formati standard**: utilizza valori di formato standard come «date-time» o «date» per date e ore. ISO-8601
+ Nomi di **parametri chiari: utilizza nomi** di parametri descrittivi che ne indichino chiaramente lo scopo.
+ **Marcatura dei campi obbligatoria**: contrassegna correttamente i parametri come obbligatori o facoltativi in base al comportamento dell'API.
## Estensioni supportate
Supportiamo estensioni OpenAPI personalizzate per migliorare l'esperienza utente.
**x-amzn-form-display-name**
Utilizzalo a livello di parametro per sovrascrivere il nome di campo predefinito visualizzato nei moduli di conferma. Attualmente supportato solo per i parametri del corpo della richiesta.
```
"x-amzn-form-display-name": "User Name"
```
**tipo di operazione x-amzn**
Definisce se un'operazione deve essere trattata come «lettura» o «scrittura». Per impostazione predefinita, i metodi GET sono operazioni di «lettura» e tutti gli altri metodi HTTP sono operazioni di «scrittura».
```
"x-amzn-operation-type": "read"
```
## Convalida dello schema e gestione degli errori
Quando carichi una specifica OpenAPI, eseguiamo una convalida completa.
+ **Convalida della dimensione del file**: garantisce che le specifiche non superino 1 MB.
+ **Convalida del conteggio delle operazioni**: verifica che siano state definite tra 1 e 100 operazioni.
+ **Convalida della struttura dello schema**: verifica la presenza di campi obbligatori e la corretta formattazione.
+ **Convalida dello schema di sicurezza: convalida** i metodi di autenticazione supportati.
+ **Convalida del tipo di contenuto**: assicura che venga utilizzato solo application/json .
Gli errori di convalida vengono visualizzati sotto l'editor dello schema e devono essere risolti prima di poter creare l'integrazione. I problemi di convalida più comuni includono:
+ Campi obbligatori mancanti (openapi, info, servers, paths).
+ Schemi di percorso o ID operativi non validi.
+ Funzionalità dello schema non supportate (matrici, parole chiave di composizione).
+ Descrizioni mancanti o troppo lunghe.
+ Riferimenti circolari nelle definizioni degli schemi.
## Gestione dell'integrazione delle specifiche OpenAPI
Dopo aver creato l'integrazione con la specifica OpenAPI, puoi gestirla tramite diverse opzioni.
### Condividi l'integrazione
Puoi condividere i connettori di azione delle specifiche OpenAPI con altri utenti della tua organizzazione.
1. **Dalla pagina dei dettagli dell'integrazione con OpenAPI, scegli Condividi.**
1. Configura le opzioni di condivisione:
+ **Condividi con utenti specifici**: inserisci nomi utente o indirizzi e-mail.
+ **Condividi con l'organizzazione**: rendilo disponibile a tutti gli utenti dell'organizzazione.
1. Imposta i livelli di autorizzazione per l'accesso condiviso.
1. Scegli **Condividi integrazione** per applicare le impostazioni di condivisione.
### Elimina l'integrazione
Segui questi passaggi per rimuovere definitivamente la tua integrazione OpenAPI.
1. **Dalla pagina dei dettagli dell'integrazione con OpenAPI, scegli Elimina.**
1. Esamina l'impatto dell'eliminazione, inclusi eventuali flussi di lavoro o automazioni che utilizzano questa integrazione.
1. Digita il nome dell'integrazione per confermare l'eliminazione.
1. Scegli **Elimina integrazione** per rimuoverla definitivamente.
## Risoluzione dei problemi di integrazione delle specifiche OpenAPI
Usa questi suggerimenti per la risoluzione dei problemi più comuni di integrazione delle specifiche OpenAPI.
Errori di convalida dei dati
Assicurati che la tua specifica OpenAPI segua il formato corretto e includa tutti i campi obbligatori. Usa un validatore OpenAPI per controllare lo schema prima dell'importazione.
Nessuna attività generata
Verifica che la tua specifica OpenAPI includa definizioni di percorso con metodi HTTP e ID operativi. Le azioni vengono generate in base alle operazioni definite nello schema.
Errori di autenticazione
Verifica che lo schema di autenticazione definito nella tua specifica OpenAPI corrisponda ai requisiti API effettivi e che le credenziali siano configurate correttamente.
Errori di esecuzione delle azioni
Esamina i parametri di azione e assicurati che corrispondano alle definizioni dei parametri nella tua specifica OpenAPI, inclusi i campi e i tipi di dati obbligatori.