Amazon API Gateway REST API tahapan sebagai target

Target API REST API Gateway menghubungkan gateway Anda ke tahap REST API Anda. Gateway menerjemahkan permintaan MCP yang masuk ke dalam permintaan HTTP ke REST API Anda dan menangani pemformatan respons. Saat Anda menambahkan atau memperbarui target API Gateway, AgentCore Gateway memanggil API GetExportAPI Gateway atas nama Anda.

Anda dapat menentukan filter alat dan penggantian alat dalam konfigurasi target Anda. Filter alat memungkinkan Anda membuat jalur sumber daya tertentu dan kombinasi metode HTTP tersedia sebagai alat di gateway Anda. Filter ini membuat daftar izin yang hanya mengekspos operasi yang Anda tentukan sebagai alat.

Anda juga dapat mengonfigurasi tahap API Gateway REST API sebagai target gateway dari konsol API Gateway. Untuk mempelajari selengkapnya, lihat Menambahkan tahapan ke AgentCore gateway di dokumentasi Amazon API Gateway.

Pertimbangan dan keterbatasan utama

Saat menggunakan API Gateway REST API stage sebagai target, ingatlah persyaratan dan batasan berikut:

Konfigurasi Alat API Gateway

Saat menambahkan API Gateway REST API sebagai target gateway, Anda perlu menyediakan konfigurasi alat API Gateway. Konfigurasi alat API Gateway menentukan operasi mana dari REST API Anda yang diekspos sebagai alat. Ini memerlukan daftar filter alat untuk memilih operasi yang akan diekspos, dan secara opsional menerima penggantian alat untuk menyesuaikan metadata alat seperti nama dan deskripsi alat.

Filter Alat

Filter alat memungkinkan Anda memilih operasi REST API menggunakan kombinasi jalur dan metode. Setiap filter mendukung dua strategi pencocokan jalur:

Setiap filter menentukan jalur dan daftar metode HTTP. Filter menyelesaikan kombinasi yang cocok yang ada di API Anda. Beberapa filter dapat tumpang tindih dan duplikat secara otomatis di-de-duplikasi.

Penggantian Alat

Secara default, nama alat MCP diambil dari kombinasi operationId untuk setiap jalur dan metode yang cocok dengan filter Anda. Jika tidak ada kecocokan operationId untuk filter, Anda memerlukan penggantian alat yang sesuai yang memberikan nama. Jika nama operationId dan nama override hilang, pembuatan target dan pembaruan akan gagal validasi. Untuk informasi selengkapnya tentang nama alat di AgentCore Gateway, lihat Memahami bagaimana alat AgentCore Gateway diberi nama.

Penggantian alat bersifat opsional. Mereka memungkinkan Anda untuk menyesuaikan nama alat atau deskripsi untuk operasi tertentu setelah pemfilteran. Setiap override harus menentukan jalur eksplisit dan metode HTTP tunggal. Wildcard tidak didukung. Override harus cocok dengan operasi yang ada di API Anda dan harus sesuai dengan salah satu operasi yang diselesaikan oleh filter Anda. Anda tidak dapat mengganti operasi yang tidak dipilih. Jika Anda mengalami kesalahan dengan impor dari operasi tanpa operationId Anda dapat menggunakan alat ganti sebagai gantinya.

Contoh konfigurasi alat API Gateway

Contoh konfigurasi alat API Gateway berikut menunjukkan cara menggunakan filter dan penggantian. Semua contoh menggunakan API dengan jalur dan metode berikut:

/pets/{petId} - GET
/pets/{petId}  - POST
/pets/{petId}  - OPTIONS
/pets          - GET
/pets          - OPTIONS
/              - GET

Jalur kartu liar dan daftar metode

Konfigurasi Alat:

{
  "filterPath": "/pets/*",
  "methods": ["GET", "POST"]
}

Hasil

Jalur eksplisit dan daftar metode

Konfigurasi Alat:

{
  "filterPath": "/pets/{petId}",
  "methods": ["GET", "POST"]
}

Hasil

Jalur eksplisit dan daftar metode eksplisit (paling spesifik)

Konfigurasi Alat:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["POST"]
    },
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    }
  ]
}

Hasil

Campur dan cocokkan jalur eksplisit dan wildcard:

Konfigurasi Alat:

{
  [
    {
        "filterPath": "/pets/{petId}",
        "methods": ["GET"]
    },
    {
        "filterPath": "/*",
        "methods": ["GET"]
    }
  ]
}

Hasil

Filter alat dan penggantian alat

Anda dapat menyediakan filter alat dan menambahkan override. Override menentukan jalur sumber daya di REST API, seperti /pets, dan metode HTTP untuk mengekspos jalur yang ditentukan. Override harus secara eksplisit cocok dengan jalur yang ada di REST API.

Konfigurasi Alat

{
  "toolFilters": [
    {
      "filterPath": "/pets/*",
      "methods": ["GET", "POST"]
    },
    {
      "filterPath": "/",
      "methods": ["GET"]
    }
  ],
  "toolOverrides": [
    {
      "path": "/pets/{petId}",
      "method": "GET",
      "name": "GetPetById",
      "description": "Retrieve a specific pet by its ID"
    }
  ]
}

Hasil

Ekspor API Gateway

Untuk menyiapkan target API Gateway Anda, AgentCore Gateway memanggil GetExportoperasi API Gateway atas nama Anda untuk mendapatkan ekspor definisi API Anda yang diformat OpenAPI 3.0. Ini membantu gateway menerjemahkan permintaan MCP masuk dengan benar ke dalam permintaan HTTP dan menangani respons. Berikut ini adalah pertimbangan saat AgentCore Gateway memanggil GetExport operasi:

Memperbarui OperationId pada REST API

Anda dapat memperbarui REST API Anda untuk memastikan bahwa definisi OpenAPI yang dikembalikan oleh GetExporttelah operationId disetel. Ini adalah alternatif untuk menyediakan penggantian alat. Berikut ini menjelaskan dua cara untuk mengaturoperationId.

Setel operationId dengan memperbarui definisi OpenAPI Anda

Ekspor definisi OpenAPI dari tahap API yang Anda gunakan dengan memanggil GetExport, memperbarui operasi yang hilangoperationId, dan mengimpor ulang API Anda.

Setel operationId dengan memperbarui metode REST API

Anda dapat mengonfigurasi Metode API Gateway Anda untuk menambahkan operationName menggunakan UpdateMethodperintah. Saat API Anda diekspor, operationName berubah menjadi. operationId

Metode otorisasi keluar yang didukung untuk API Gateway API

Anda dapat mengonfigurasi target AgentCore Gateway untuk melakukan panggilan ke API dengan autentikasi keluar.

AgentCore Gateway mendukung jenis otorisasi keluar berikut untuk Target API Gateway:

Untuk mempelajari lebih lanjut, lihat Mengatur otorisasi keluar untuk gateway Anda.

Otorisasi keluar IAM

API Gateway memungkinkan Anda mengamankan REST API Anda dengan IAM. Ketika otorisasi IAM diaktifkan, klien harus menggunakan Signature Version 4 (SigV4 atau Sigv4a) untuk menandatangani permintaan mereka dengan kredensi. AWS

Untuk mengatur otorisasi keluar IAM

Kebijakan sumber daya API Gateway

Kebijakan sumber daya API Gateway adalah dokumen kebijakan JSON yang Anda lampirkan ke API REST API Gateway API untuk mengontrol apakah prinsipal tertentu dapat memanggil API. Agar AgentCore Gateway memanggil REST API Anda dengan kebijakan sumber daya, Anda harus melakukan hal berikut:

Berikut ini adalah contoh kebijakan sumber daya API yang memberikan akses AgentCore Gateway ke REST API Anda.

{
"Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:us-west-2:111122223333:abcd123/*/*/*",
      "Condition": {
        "ArnEquals": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:us-west-2:111122223333:gateway/my-gateway-d4jrgkaske"
        }
      }
    }
  ]
}

Otorisasi keluar kunci API

Untuk menyiapkan otorisasi keluar dengan kunci API, Anda menggunakan layanan AgentCore Identity untuk membuat penyedia kredensi dan dengan kunci API yang telah dikonfigurasi melalui API Gateway.

Untuk mengatur otorisasi keluar kunci API