View a markdown version of this page

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

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

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 masuk ke 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 ToolSpec dengan masing-masing LLM hilir, bidang data akan gagal. Kesalahan umum adalah nama properti melebihi panjang yang diizinkan atau nama yang berisi 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 menggunakan 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 (Pemalsuan Per Server-Side mintaan)

  • Ekspiltrasi kredenSIAL 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 di aplikasi Anda

  • Hindari menggunakan parameter yang memungkinkan substitusi domain atau host arbitrer

  • 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 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-tenant. 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 Jenis data dasar (string, angka, integer, boolean, array, objek) Validasi bidang yang diperlukan Struktur objek bersarang Definisi array dengan spesifikasi item

Komposisi Skema Spesifikasi satuDari 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 khusus di luar daftar yang didukung Jenis media biner

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

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

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

Operasi panggilan balik dan Webhook Callback Definisi Webhook

Request/Response Bad an permintaan dan respons JSON Badan permintaan dan respons XML Kode status HTTP standar (200, 201, 400, 404, 500, dll.)

Tautan Tautan antar operasi

Strategi otorisasi

Jenis otorisasi keluar berikut didukung untuk target OpenAPI:

  • Tidak ada otorisasi — Gateway memanggil target OpenAPI tanpa otorisasi yang telah dikonfigurasi sebelumnya. Pendekatan ini tidak dianjurkan.

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

  • Kunci API — Gateway menggunakan penyedia kredensia kunci API untuk mengotentikasi 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 kredentif peran layanan gateway. Anda mengonfigurasi IamCredentialProvider dengan nama layanan yang diperlukan untuk penandatanganan SIGv4 dan Wilayah opsional (default ke Wilayah gateway).

penting

Otorisasi keluar IAM (SIGv4) mengharuskan target OpenAPI dihosting di belakang AWS layanan yang secara native mendukung otentikasi IAM. 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 AgentCore Amazon

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

Untuk informasi selengkapnya tentang mengatur otorisasi keluar, lihat Menyi apkan otorisasi keluar untuk gateway Anda.

Spesifikasi skema OpenAPI

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

  • Untuk informasi tentang format spesifikasi OpenAPI, lihat Spesifikasi OpenAPI.

  • Untuk informasi tentang fitur yang didukung dan tidak didukung saat menggunakan spesifikasi OpenAPI dengan AgentCore Gateway, lihat tabel di dukungan fitur OpenAPI. Patuhi persyaratan ini untuk mencegah kesalahan selama pembuatan dan pemanggilan target.

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

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

  • Tempelkan 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 yang 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 yang 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"}
  ]
}