Integrasi Spesifikasi OpenAPI - Amazon Cepat
Apa yang dapat Anda lakukanSebelum Anda mulaiSiapkan spesifikasi dan otentikasi OpenAPISiapkan integrasi Spesifikasi OpenAPIPersyaratan format dan polaFitur yang tidak didukungPraktik terbaik skemaEkstensi yang didukungValidasi skema dan penanganan kesalahanKelola integrasi Spesifikasi OpenAPIMemecahkan masalah integrasi Spesifikasi OpenAPI

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Integrasi Spesifikasi OpenAPI

Dengan integrasi Spesifikasi OpenAPI, Anda dapat membuat integrasi khusus berdasarkan skema OpenAPI. Ini memungkinkan Anda untuk terhubung ke API apa pun yang menyediakan spesifikasi OpenAPI. Integrasi ini hanya mendukung eksekusi tindakan dan memerlukan Amazon Quick Pro tier atau lebih tinggi.

Apa yang dapat Anda lakukan

Integrasi Spesifikasi OpenAPI menyediakan konektivitas berbasis skema untuk membantu Anda bekerja dengan kustom. APIs

Konektor aksi

Lakukan tindakan berdasarkan spesifikasi OpenAPI. Jalankan panggilan API, kelola sumber daya, dan berinteraksi dengan layanan kustom melalui tindakan yang dihasilkan secara dinamis berdasarkan skema yang disediakan.

Konfigurasi berbasis skema

Impor spesifikasi OpenAPI untuk secara otomatis menghasilkan tindakan dan tindakan yang tersedia. Support untuk validasi skema JSON dan pemetaan parameter.

Sebelum Anda mulai

Sebelum Anda mengatur integrasi Spesifikasi OpenAPI, pastikan Anda memiliki yang berikut:

  • Spesifikasi OpenAPI (versi 3.0.0 atau lebih tinggi) untuk API target Anda.

  • Kredensi otentikasi API (kunci API, OAuth, atau lainnya).

  • Amazon Quick Author atau lebih tinggi.

  • Dokumentasi API dan akses titik akhir.

Siapkan spesifikasi dan otentikasi OpenAPI

Sebelum menyiapkan integrasi di Amazon Quick, siapkan spesifikasi OpenAPI dan kredensi otentikasi Anda. Spesifikasi OpenAPI Anda harus memenuhi persyaratan khusus untuk integrasi yang berhasil.

Persyaratan dasar

Spesifikasi OpenAPI Anda harus memenuhi persyaratan dasar ini.

  • Versi OpenAPI - Versi 3.0.0 atau lebih tinggi diperlukan.

  • Format file - format JSON saja (aplikasi/json).

  • Batas ukuran file - Maksimum 1MB untuk seluruh spesifikasi OpenAPI.

  • Batas operasi - Minimum 1 dan maksimum 100 operasi API per konektor.

Bidang skema yang diperlukan

Spesifikasi OpenAPI Anda harus menyertakan bagian yang diperlukan ini.

openapi

Versi OpenAPI yang digunakan (harus “3.0.0" atau lebih tinggi).

Info

Informasi layanan termasuk judul, deskripsi, dan versi.

server

URL dasar dan informasi server untuk konektivitas API.

jalan

Definisi titik akhir API dengan metode dan operasi HTTP.

Skema otentikasi yang didukung

Siapkan kredensyal otentikasi berdasarkan metode otentikasi yang didukung dalam spesifikasi OpenAPI.

OAuth 2.0

Mendukung aliran Hibah Kode Otorisasi dan Kredensyal Klien Hibah. Memerlukan definisi AuthorizationUrl, TokenUrl, dan cakupan dalam skema keamanan.

Kunci API

Otentikasi kunci API diteruskan dalam parameter kueri atau header.

Tidak ada otentikasi

Opsi default ketika tidak ada skema keamanan yang ditentukan dalam spesifikasi.

catatan

Skema otentikasi yang tidak didukung dalam spesifikasi OpenAPI akan diabaikan, dan konektor akan default tanpa otentikasi.

Siapkan integrasi Spesifikasi OpenAPI

Setelah menyiapkan spesifikasi OpenAPI dan kredensi otentikasi Anda, ikuti langkah-langkah berikut untuk membuat integrasi Spesifikasi OpenAPI Anda.

  1. Di konsol Amazon Quick, pilih Integrasi.

  2. Klik Tambah (ditambah tombol “+”).

  3. Pada halaman Tambah Skema, pilih Impor Skema dan pilih skema untuk diimpor.

  4. Pilih Selanjutnya.

  5. Isi detail integrasi termasuk nama dan deskripsi.

  6. Tinjau tindakan yang tersedia yang dihasilkan dari spesifikasi OpenAPI Anda.

  7. Pilih Buat dan lanjutkan.

  8. Pilih pengguna untuk berbagi integrasi dengan.

  9. Klik Berikutnya.

Hasil yang diharapkan

Setelah penyiapan berhasil, integrasi Spesifikasi OpenAPI Anda muncul di daftar integrasi dengan tindakan yang dihasilkan secara dinamis berdasarkan skema Anda. Integrasi ini tersedia untuk digunakan dalam alur kerja Amazon Quick, otomatisasi, dan agen AI, dengan tugas yang sesuai dengan titik akhir yang ditentukan dalam spesifikasi OpenAPI Anda.

Persyaratan format dan pola

Spesifikasi OpenAPI Anda harus mengikuti persyaratan format ini.

  • Pola jalur - Harus mengikuti pola: ^/[^/]*(/[^/]*)*$ dan mulai dengan garis miring (/).

  • Operasi IDs - Harus mengikuti pola:^[a-zA-Z0-9_ ]{1,256}$.

  • Deskripsi - Diperlukan untuk semua operasi dan parameter, maksimum 5000 karakter.

  • Jenis konten - Hanya application/json didukung untuk badan permintaan dan respons.

Fitur yang tidak didukung

Fitur OpenAPI berikut tidak didukung dan akan menyebabkan kesalahan validasi.

  • Jenis array - Skema dengan tipe array (misalnya,{"type": "array", "items": {"string"}}) tidak didukung.

  • Kata kunci komposisi - AlloF, OneOf, AnyOf, dan bukan kata kunci tidak didukung.

  • Referensi melingkar - Referensi melingkar atau siklik ($ref di dalam $ref) tidak didukung.

  • Struktur bersarang yang kompleks - Hindari struktur objek bersarang dalam jika memungkinkan.

Praktik terbaik skema

Ikuti praktik terbaik ini saat membuat spesifikasi OpenAPI Anda.

Tulis deskripsi yang efektif

Gunakan panduan ini untuk menulis deskripsi yang jelas dan bermanfaat.

  • Deskripsi operasi - Jelaskan apa yang dilakukan operasi, kapan menggunakannya, dan bagaimana perilakunya.

  • Deskripsi parameter - Secara ringkas menjelaskan tujuan parameter dan dampak pada perilaku operasi.

  • Konten mandiri - Pastikan deskripsi memberikan panduan yang memadai tanpa referensi eksternal.

  • Kejelasan ketergantungan - Membuat dependensi antara operasi eksplisit dalam deskripsi.

  • Referensi operasi - Gunakan operationId saat merujuk ke operasi lain, bukan jalur API.

Rekomendasi struktur parameter

Susun parameter Anda untuk kegunaan yang optimal.

  • Ratakan objek kompleks - Alih-alih objek bersarang, gunakan parameter terpisah (misalnya, start_date, start_time, end_date, end_time).

  • Gunakan format standar - Gunakan nilai format standar seperti “tanggal-waktu” atau “tanggal” untuk tanggal dan waktu ISO-8601.

  • Hapus nama parameter - Gunakan nama parameter deskriptif yang dengan jelas menunjukkan tujuannya.

  • Penandaan bidang wajib - Tandai parameter dengan benar sesuai kebutuhan atau opsional berdasarkan perilaku API.

Ekstensi yang didukung

Kami mendukung ekstensi OpenAPI khusus untuk meningkatkan pengalaman pengguna.

x-amzn-form-display-nama

Gunakan pada tingkat parameter untuk mengganti nama bidang default yang ditampilkan dalam formulir konfirmasi. Saat ini hanya didukung untuk parameter badan permintaan.

"x-amzn-form-display-name": "User Name"
x-amzn-operation-type

Tentukan apakah suatu operasi harus diperlakukan sebagai “baca” atau “tulis”. Secara default, metode GET adalah operasi “baca” dan semua metode HTTP lainnya adalah operasi “tulis”.

"x-amzn-operation-type": "read"

Validasi skema dan penanganan kesalahan

Saat Anda mengunggah spesifikasi OpenAPI, kami melakukan validasi komprehensif.

  • Validasi ukuran file - Memastikan spesifikasi tidak melebihi 1MB.

  • Validasi jumlah operasi - Verifikasi antara 1-100 operasi didefinisikan.

  • Validasi struktur skema - Memeriksa bidang yang diperlukan dan pemformatan yang tepat.

  • Validasi skema keamanan - Memvalidasi metode otentikasi yang didukung.

  • Validasi tipe konten - Memastikan hanya application/json digunakan.

Kesalahan validasi muncul di bawah editor skema dan harus diselesaikan sebelum integrasi dapat dibuat. Masalah validasi umum meliputi:

  • Bidang wajib tidak ada (openapi, info, server, jalur).

  • Pola jalur atau operasi tidak valid. IDs

  • Fitur skema yang tidak didukung (array, kata kunci komposisi).

  • Deskripsi yang hilang atau terlalu panjang.

  • Referensi melingkar dalam definisi skema.

Kelola integrasi Spesifikasi OpenAPI

Setelah Anda membuat integrasi Spesifikasi OpenAPI, Anda dapat mengelolanya melalui beberapa opsi.

Integrasi berbagi

Anda dapat berbagi konektor tindakan Spesifikasi OpenAPI dengan pengguna lain di organisasi Anda.

  1. Dari halaman detail integrasi OpenAPI, pilih Bagikan.

  2. Konfigurasikan opsi berbagi:

    • Bagikan dengan pengguna tertentu - Masukkan nama pengguna atau alamat email.

    • Bagikan dengan organisasi - Sediakan untuk semua pengguna di organisasi Anda.

  3. Tetapkan tingkat izin untuk akses bersama.

  4. Pilih Bagikan integrasi untuk menerapkan pengaturan berbagi.

Hapus integrasi

Ikuti langkah-langkah ini untuk menghapus integrasi OpenAPI Anda secara permanen.

  1. Dari halaman detail integrasi OpenAPI, pilih Hapus.

  2. Tinjau dampak penghapusan, termasuk alur kerja atau otomatisasi apa pun yang menggunakan integrasi ini.

  3. Ketik nama integrasi untuk mengonfirmasi penghapusan.

  4. Pilih Hapus integrasi untuk menghapusnya secara permanen.

Memecahkan masalah integrasi Spesifikasi OpenAPI

Gunakan tips pemecahan masalah ini untuk mengatasi masalah integrasi Spesifikasi OpenAPI yang umum.

Kesalahan validasi skema

Pastikan spesifikasi OpenAPI Anda mengikuti format yang benar dan mencakup semua bidang wajib. Gunakan validator OpenAPI untuk memeriksa skema Anda sebelum mengimpor.

Tidak ada tugas yang dihasilkan

Verifikasi bahwa spesifikasi OpenAPI Anda menyertakan definisi jalur dengan metode dan operasi HTTP. IDs Tindakan dihasilkan berdasarkan operasi yang ditentukan dalam skema Anda.

Kegagalan otentikasi

Periksa apakah skema otentikasi yang ditentukan dalam spesifikasi OpenAPI Anda cocok dengan persyaratan API yang sebenarnya dan kredensialnya dikonfigurasi dengan benar.

Kegagalan eksekusi tindakan

Tinjau parameter tindakan dan pastikan parameter tersebut cocok dengan definisi parameter dalam spesifikasi OpenAPI Anda, termasuk bidang wajib dan tipe data.