View a markdown version of this page

Target skema OpenAPI - Batuan Dasar Amazon AgentCore
Pertimbangan dan batasan utamaStrategi otorisasiSpesifikasi skema OpenAPI

Target skema OpenAPI

OpenAPI (sebelumnya dikenal sebagai Swagger) adalah standar yang banyak digunakan untuk menggambarkan RESTful API. Gateway mendukung spesifikasi OpenAPI 3.0 untuk menentukan target API.

Target OpenAPI menghubungkan gateway Anda ke REST API yang ditentukan menggunakan spesifikasi OpenAPI. Gateway menerjemahkan permintaan MCP yang masuk ke dalam permintaan HTTP ke API ini dan menangani pemformatan respons.

Tinjau pertimbangan dan batasan utama, termasuk dukungan fitur, untuk membantu Anda memutuskan apakah target OpenAPI berlaku untuk kasus penggunaan Anda. Jika ya, Anda dapat membuat skema yang mengikuti spesifikasi dan kemudian mengatur izin untuk gateway untuk dapat mengakses target. Pilih topik untuk mempelajari lebih lanjut:

Pertimbangan dan batasan utama

penting

Spesifikasi OpenAPI harus menyertakan operationId bidang untuk semua operasi yang ingin Anda ekspos sebagai alat. OperationId digunakan sebagai nama alat di antarmuka MCP.

Saat menggunakan target OpenAPI, ingatlah persyaratan dan batasan berikut:

  • OpenAPI versi 3.0 dan 3.1 didukung (Swagger 2.0 tidak didukung)

  • File OpenAPI harus bebas dari kesalahan semantik

  • Atribut server harus memiliki URL yang valid dari titik akhir yang sebenarnya

  • Hanya jenis application/json konten yang didukung penuh

  • Fitur skema kompleks seperti OneOf, AnyOf, dan allOf tidak didukung

  • Serializer parameter jalur dan serializer parameter untuk parameter kueri, header, dan cookie tidak didukung

  • Setiap LLM akan memiliki ToolSpec kendala. Jika OpenAPI memiliki APIs/properties/object nama yang tidak sesuai dengan ToolSpec LLM hilir masing-masing, bidang data akan gagal. Kesalahan umum adalah nama properti melebihi panjang yang diizinkan atau nama yang mengandung karakter yang tidak didukung.

Untuk hasil terbaik dengan target OpenAPI:

  • Selalu sertakan operationId di semua operasi

  • Gunakan struktur parameter sederhana alih-alih serialisasi kompleks

  • Menerapkan otentikasi dan otorisasi di luar spesifikasi

  • Hanya gunakan jenis media yang didukung untuk kompatibilitas maksimum

Praktik terbaik keamanan untuk parameter URL

Awas

Saat menentukan URL server dalam spesifikasi OpenAPI Anda, hindari penggunaan pola parameter URL yang terlalu permisif yang dapat mengekspos gateway Anda ke risiko keamanan.

Parameter URL dalam definisi server OpenAPI memungkinkan konfigurasi titik akhir dinamis. Namun, pola tertentu dapat menimbulkan kerentanan keamanan jika tidak dibatasi dengan benar. Secara khusus, hindari menggunakan pola domain yang sepenuhnya dinamis seperti:

  • https://{yourDomain}/- Memungkinkan substitusi domain sewenang-wenang

  • https://{subdomain}.{env}.{domain}.com- Beberapa placeholder yang tidak dibatasi

  • https://{host}/api/- Parameter host tidak terbatas

Pola-pola ini berpotensi dieksploitasi untuk:

  • Mengalihkan permintaan ke titik akhir yang tidak diinginkan atau berbahaya

  • Akses sumber daya jaringan internal (Server-Side Minta Pemalsuan)

  • Eksfiltrasi kredensyal atau data sensitif

Praktik yang direkomendasikan:

  • Gunakan URL statis yang sepenuhnya memenuhi syarat bila memungkinkan: https://api.example.com/v1

  • Batasi parameter ke subdomain dalam domain terkontrol Anda dan terapkan validasi dalam aplikasi Anda

  • Hindari menggunakan parameter yang memungkinkan domain arbitrer atau substitusi host

  • Terapkan validasi tambahan di API Anda untuk memverifikasi bahwa nilai parameter runtime cocok dengan pola yang diharapkan

AgentCore Gateway secara otomatis memvalidasi parameter wilayah dan memblokir permintaan ke rentang IP pribadi.

Contoh konfigurasi URL server yang aman:

{
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ]
}

Jika parameter dinamis diperlukan, gunakan domain yang sepenuhnya memenuhi syarat dengan placeholder minimal dan batasan enum:

{
  "servers": [
    {
      "url": "https://{tenant}.api.example.com/v1",
      "variables": {
        "tenant": {
          "default": "default-tenant",
          "description": "Customer tenant identifier",
          "enum": ["tenant1", "tenant2", "tenant3"]
        }
      }
    }
  ]
}

Pendekatan ini membatasi parameter URL ke subdomain tertentu dalam domain terkontrol Anda sambil mempertahankan fleksibilitas untuk penerapan multi-penyewa. Menggunakan pembatasan enum mencegah nilai arbitrer dan membantu melindungi terhadap serangan SSRF dengan membatasi parameter ke nilai aman yang telah ditentukan sebelumnya. Selain itu, selalu validasi nilai penyewa dalam logika aplikasi Anda.

Dalam mempertimbangkan untuk menggunakan target skema OpenAPI dengan AgentCore Gateway, tinjau tabel dukungan fitur berikut.

Dukungan fitur OpenAPI

Tabel berikut menguraikan fitur OpenAPI yang didukung dan tidak didukung oleh Gateway:

Fitur yang Didukung Fitur-Fitur yang Tidak Didukung

Definisi Skema Tipe data dasar (string, angka, integer, boolean, array, objek) Validasi bidang yang diperlukan Struktur objek bersarang Definisi array dengan spesifikasi item

Skema Komposisi OneOf spesifikasi AnyOf spesifikasi AlloF

Metode HTTP Metode HTTP standar (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)

Skema Keamanan Skema keamanan pada tingkat spesifikasi OpenAPI (otentikasi harus dikonfigurasi menggunakan konfigurasi otorisasi keluar Gateway)

Jenis Media application/json application/xml multipart/form -data -www-form-urlencoded application/x

Jenis Media Jenis media kustom di luar daftar yang didukung Jenis media biner

Parameter Jalur Definisi parameter jalur sederhana (Contoh: /users/ {userId})

Serialisasi Parameter Serialisasi parameter jalur kompleks (Contoh:/users { ;id\*} { ?metadata}) Array parameter kueri dengan serialisasi kompleks Serialisasi parameter header Serializer parameter cookie

Parameter Kueri Definisi parameter kueri dasar Jenis string, angka, dan boolean sederhana

Callback dan Webhooks Operasi callback Definisi Webhook

Request/Response Badan permintaan dan respons JSON badan permintaan dan respons XMLKode status HTTP standar (200, 201, 400, 404, 500, dll.)

Tautan Tautan antar operasi

Strategi otorisasi

Jenis otorisasi keluar berikut didukung untuk target OpenAPI:

  • Tanpa otorisasi - Gateway memanggil target OpenAPI tanpa otorisasi yang telah dikonfigurasi sebelumnya. Pendekatan ini tidak disarankan.

  • OAuth — Gateway mendukung OAuth berkaki dua (jenis hibah Kredensial Klien) dan OAuth berkaki tiga (jenis hibah Kode Otorisasi). Anda mengonfigurasi penyedia otorisasi di Amazon Bedrock AgentCore Identity di akun dan Wilayah yang sama dengan gateway.

  • Kunci API — Gateway menggunakan penyedia kredensi kunci API untuk mengautentikasi dengan target OpenAPI. Anda mengonfigurasi penyedia kunci API di Amazon Bedrock AgentCore Identity di akun dan Wilayah yang sama dengan gateway.

  • IAM (AWS Signature Version 4 (Sig V4)) - Gateway menandatangani permintaan ke target OpenAPI menggunakan SigV4 dengan kredensyal peran layanan gateway. Anda mengonfigurasi nama layanan IamCredentialProvider yang diperlukan untuk penandatanganan SigV4 dan Region opsional (default ke Region gateway).

penting

Otorisasi keluar IAM (SigV4) mengharuskan target OpenAPI di-host di belakang layanan yang secara native mendukung otentikasi IAM. AWS Gateway menandatangani permintaan keluar dengan SiGv4 tetapi tidak mengubah konfigurasi otentikasi pada target. Layanan target harus dapat memverifikasi tanda tangan Sigv4.

AWS Layanan berikut secara native mendukung otentikasi IAM dan kompatibel dengan otorisasi keluar IAM untuk target OpenAPI:

  • Amazon API Gateway

  • URL Fungsi Lambda

  • Gerbang Dasar Dasar Amazon AgentCore

Layanan yang tidak memverifikasi tanda tangan Sigv4 secara native, seperti Application Load Balancer atau titik akhir Amazon EC2 langsung, tidak kompatibel dengan otorisasi keluar IAM. Jika target OpenAPI Anda di-host di belakang salah satu layanan ini, gunakan otorisasi kunci OAuth atau API sebagai gantinya.

Untuk informasi selengkapnya tentang pengaturan otorisasi keluar, lihat Menyiapkan otorisasi keluar untuk gateway Anda.

Spesifikasi skema OpenAPI

Spesifikasi OpenAPI mendefinisikan REST API yang akan diekspos oleh Gateway Anda. Lihat sumber daya berikut saat menyiapkan spesifikasi OpenAPI Anda:

Setelah Anda menentukan skema OpenAPI Anda, Anda dapat melakukan salah satu hal berikut:

  • Unggah ke bucket Amazon S3 dan lihat lokasi S3 saat Anda menambahkan target ke gateway Anda.

  • Tempel definisi sebaris saat Anda menambahkan target ke gateway Anda.

Perluas bagian untuk melihat contoh spesifikasi OpenAPI yang didukung dan tidak didukung:

Berikut ini menunjukkan contoh spesifikasi OpenAPI didukung

Contoh spesifikasi OpenAPI yang didukung:

{
  "openapi": "3.0.0",
  "info": {
    "title": "Weather API",
    "version": "1.0.0",
    "description": "API for retrieving weather information"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/weather": {
      "get": {
        "summary": "Get current weather",
        "description": "Returns current weather information for a location",
        "operationId": "getCurrentWeather",
        "parameters": [
          {
            "name": "location",
            "in": "query",
            "description": "City name or coordinates",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "units",
            "in": "query",
            "description": "Units of measurement (metric or imperial)",
            "required": false,
            "schema": {
              "type": "string",
              "enum": ["metric", "imperial"],
              "default": "metric"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "location": {
                      "type": "string"
                    },
                    "temperature": {
                      "type": "number"
                    },
                    "conditions": {
                      "type": "string"
                    },
                    "humidity": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request"
          },
          "404": {
            "description": "Location not found"
          }
        }
      }
    }
  }
}

Berikut ini menunjukkan contoh lain dari spesifikasi OpenAPI didukung.

{
  "openapi": "3.0.0",
  "info": {
    "title": "Search API",
    "version": "1.0.0",
    "description": "API for searching content"
  },
  "servers": [
    {
      "url": "https://api.example.com/v1"
    }
  ],
  "paths": {
    "/search": {
      "get": {
        "summary": "Search for content",
        "operationId": "searchContent",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Search query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of results",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "snippet": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    }
  }
}

Berikut ini menunjukkan contoh skema yang tidak didukung dengan OneOf:

{
  "oneOf": [
    {"$ref": "#/components/schemas/Pencil"},
    {"$ref": "#/components/schemas/Pen"}
  ]
}