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

Tahapan API REST API Gateway Amazon sebagai target

Target API REST API Gateway menghubungkan gateway Anda ke https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-stages.html tahap REST API Anda. Gateway menerjemahkan permintaan MCP masuk ke permintaan HTTP ke REST API Anda dan menangani pemformatan respons. Saat Anda menambahkan atau memperbarui target API Gateway, AgentCore Gateway memanggil API Gateway GetExport API 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 izinkan yang hanya menampilkan operasi yang Anda tentukan sebagai alat.

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

Pertimbangan dan batasan utama

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

Konfigurasi Alat Gateway API

Saat menambahkan API REST API Gateway 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.

Alat Filter

Filter alat memungkinkan Anda memilih operasi REST API menggunakan kombinasi jalur dan metode. Setiap filter mendukung 2 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 dide-duplikasi.

Penggantian Alat

Secara default, nama alat MCP diambil dari kombinasi jalur dan metode operationId untuk setiap jalur dan metode yang cocok dengan filter Anda. Jika tidak ada keco operationId cokan untuk filter, Anda memerlukan penggantian alat yang sesuai yang memberikan nama. Jika nama peng operationId gantian dan nama penggantian hilang, pembuatan dan pembaruan target akan gagal divalidasi. 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. Penggantian 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 penggantian alat 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 penggantian. Penggantian menentukan jalur sumber daya di REST API, seperti /pets, dan metode HTTP untuk mengekspos untuk jalur yang ditentukan. Penggantian 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 mengatur target API Gateway, AgentCore Gateway memanggil GetExport operasi untuk API Gateway atas nama Anda untuk mendapatkan ekspor definisi API yang diformat OpenAPI 3.0. Ini membantu gateway menerjemahkan permintaan MCP yang masuk dengan benar ke dalam permintaan HTTP dan menangani respons. Berikut ini adalah pertimbangan ketika AgentCore Gateway memanggil GetExport operasi:

Memperbarui OperationId di REST API Anda

Anda dapat memperbarui REST API Anda untuk memastikan bahwa definisi OpenAPI yang dikembalikan oleh GetExport telah operationId ditetapkan. Ini adalah alternatif untuk menyediakan penggantian alat. Berikut ini menjelaskan 2 cara untuk mengaturoperationId.

Mengatur 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.

Tetapkan Oper ationId dengan memperbarui metode REST API Anda

Anda dapat mengonfigurasi Metode Gateway API Anda untuk menambahkan operationName menggunakan UpdateMethod perintah. Saat API Anda diekspor, operationName berubah menjadioperationId.

Metode otorisasi keluar yang didukung untuk API Gateway API

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

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

Untuk mempelajari selengkapnya, lihat Menyiapkan 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 Tanda Tangan Versi 4 (SIGv4 atau SIGV4a) untuk menandatangani permintaan mereka dengan kredenSIAL. AWS

Cara mengatur otorisasi keluar IAM

Kebijakan sumber daya API Gateway

Kebijakan sumber daya API Gateway adalah dokumen kebijakan JSON yang Anda lampirkan ke API Gateway REST API untuk mengontrol apakah prinsipal tertentu dapat memanggil API. Agar AgentCore Gateway dapat 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 mengatur otorisasi keluar dengan kunci API, Anda menggunakan layanan AgentCore Identitas untuk membuat penyedia kredensia dan dengan kunci API yang telah Anda konfigurasikan melalui API Gateway.

Cara mengatur otorisasi keluar kunci API