Siapkan permintaan metode di API Gateway

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

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

Menyiapkan permintaan metode melibatkan melakukan tugas-tugas berikut, setelah membuat RestApisumber daya:

Anda dapat melakukan tugas-tugas ini menggunakan metode berikut:

Siapkan sumber daya API

Di API Gateway API, Anda mengekspos sumber daya yang dapat dialamatkan sebagai pohon entitas Sumber Daya API, dengan sumber daya root (/) di bagian atas hierarki. Sumber daya root relatif terhadap URL dasar API, yang terdiri dari titik akhir API dan nama panggung. Di konsol API Gateway, URI dasar ini disebut sebagai URI Invoke dan ditampilkan di editor tahap API setelah API diterapkan.

Titik akhir API dapat berupa nama host default atau nama domain khusus. Nama host default adalah dari format berikut:

{api-id}.execute-api.{region}.amazonaws.com

Dalam format ini, ini {api-id} mewakili pengenal API yang dihasilkan oleh API Gateway. {region}Variabel mewakili AWS Region (misalnya,us-east-1) yang Anda pilih saat membuat API. Nama domain kustom adalah nama yang ramah pengguna di bawah domain internet yang valid. Misalnya, jika Anda telah mendaftarkan domain internetexample.com, salah satu dari *.example.com adalah nama domain kustom yang valid. Untuk informasi selengkapnya, lihat membuat nama domain kustom.

Untuk API PetStore sampel, sumber daya root (/) mengekspos toko hewan peliharaan. Sumber /pets daya mewakili koleksi hewan peliharaan yang tersedia di toko hewan peliharaan. Ini /pets/{petId} mengekspos hewan peliharaan individu dari pengenal yang diberikan ()petId. Parameter jalur {petId} adalah bagian dari parameter permintaan.

Untuk menyiapkan sumber daya API, Anda memilih sumber daya yang ada sebagai induknya, lalu membuat sumber daya turunan di bawah sumber daya induk ini. Anda mulai dengan sumber daya root sebagai induk, menambahkan sumber daya ke induk ini, menambahkan sumber daya lain ke sumber daya turunan ini sebagai induk baru, dan seterusnya, ke pengenal induknya. Kemudian Anda menambahkan sumber daya bernama ke induk.

Perintah get-resources berikut mengambil semua sumber daya API:

aws apigateway get-resources --rest-api-id apiId

Untuk PetStore contoh API, outputnya terlihat seperti berikut:

{
    "items": [
        {
            "path": "/pets", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "6sxz2j", 
            "pathPart": "pets", 
            "parentId": "svzr2028x8"
        }, 
        {
            "path": "/pets/{petId}", 
            "resourceMethods": {
                "GET": {}
            }, 
            "id": "rjkmth", 
            "pathPart": "{petId}", 
            "parentId": "6sxz2j"
        }, 
        {
            "path": "/", 
            "id": "svzr2028x8"
        }
    ]
}

Setiap item mencantumkan pengidentifikasi sumber daya (id) dan, kecuali sumber daya root, induk langsungnya (parentId), serta nama sumber daya (pathPart). Sumber daya root istimewa karena tidak memiliki induk. Setelah memilih sumber daya sebagai induk, gunakan perintah berikut untuk menambahkan sumber daya anak:

aws apigateway create-resource --rest-api-id apiId \
    --parent-id parentId \
    --path-part resourceName

Misalnya, untuk menambahkan makanan hewan untuk dijual di PetStore situs web, gunakan perintah berikut:

aws apigateway create-resource --rest-api-id a1b2c3 \
    --parent-id svzr2028x8 \
    --path-part food

Outputnya akan terlihat seperti berikut:

{
    "path": "/food", 
    "pathPart": "food", 
    "id": "xdsvhp", 
    "parentId": "svzr2028x8"
}

Menggunakan sumber daya proxy untuk merampingkan penyiapan API

Seiring pertumbuhan bisnis, PetStore pemilik dapat memutuskan untuk menambahkan makanan, mainan, dan barang-barang terkait hewan peliharaan lainnya untuk dijual. Untuk mendukung ini, Anda dapat menambahkan/food,/toys, dan sumber daya lainnya di bawah sumber daya root. Di bawah setiap kategori penjualan, Anda mungkin juga ingin menambahkan lebih banyak sumber daya, seperti/food/{type}/{item},/toys/{type}/{item}, dll. Ini bisa membosankan. Jika Anda memutuskan untuk menambahkan lapisan tengah {subtype} ke jalur sumber daya untuk mengubah hierarki jalur menjadi/food/{type}/{subtype}/{item},/toys/{type}/{subtype}/{item}, dll., Perubahan akan merusak pengaturan API yang ada. Untuk menghindari hal ini, Anda dapat menggunakan sumber daya proxy API Gateway untuk mengekspos sekumpulan sumber daya API sekaligus.

API Gateway mendefinisikan sumber daya proxy sebagai placeholder untuk sumber daya yang akan ditentukan saat permintaan dikirimkan. Sumber daya proxy diekspresikan oleh parameter jalur khusus{proxy+}, sering disebut sebagai parameter jalur serakah. +Tanda tersebut menunjukkan sumber daya anak mana pun yang ditambahkan padanya. /parent/{proxy+}Placeholder adalah singkatan dari sumber daya apa pun yang cocok dengan pola jalur. /parent/* Anda dapat menggunakan string apa pun untuk nama parameter jalur serakah.

Perintah create-resource berikut membuat sumber daya proxy di bawah root (): /{proxy+}

aws apigateway create-resource --rest-api-id apiId \
    --parent-id rootResourceId \
    --path-part {proxy+}

Outputnya akan terlihat seperti berikut:

{
    "path": "/{proxy+}", 
    "pathPart": "{proxy+}", 
    "id": "234jdr", 
    "parentId": "svzr2028x8"
}

Untuk contoh PetStore API, Anda dapat menggunakan /{proxy+} untuk mewakili /pets dan/pets/{petId}. Sumber daya proxy ini juga dapat mereferensikan sumber daya lain (yang ada atau to-be-added)/food/{type}/{item}, seperti/toys/{type}/{item},, dll., Atau/food/{type}/{subtype}/{item},/toys/{type}/{subtype}/{item}, dll. Pengembang backend menentukan hierarki sumber daya dan pengembang klien bertanggung jawab untuk memahaminya. API Gateway hanya meneruskan apa pun yang dikirimkan klien ke backend.

API dapat memiliki lebih dari satu sumber daya proxy. Misalnya, sumber daya proxy berikut diizinkan dalam API, dengan asumsi /parent/{proxy+} bukan induk yang sama dengan. /parent/{child}/{proxy+}

/{proxy+}
/parent/{proxy+}
/parent/{child}/{proxy+}

Ketika sumber daya proxy memiliki saudara kandung non-proxy, sumber daya saudara dikecualikan dari representasi sumber daya proxy. Untuk contoh sebelumnya, /{proxy+} mengacu pada sumber daya apa pun di bawah sumber daya root kecuali sumber daya. /parent[/*] Dengan kata lain, permintaan metode terhadap sumber daya tertentu lebih diutamakan daripada permintaan metode terhadap sumber daya generik pada tingkat hierarki sumber daya yang sama.

Tabel berikut menunjukkan cara API Gateway merutekan permintaan ke sumber daya berikut untuk prod tahap API.

ANY /{proxy+}
GET /pets/{proxy+}
GET /pets/dog

Sumber daya proxy tidak dapat memiliki sumber daya anak. Sumber daya API apa pun {proxy+} setelahnya berlebihan dan ambigu. Sumber daya proxy berikut tidak diizinkan dalam API.

/{proxy+}/child
/parent/{proxy+}/{child}
/parent/{child}/{proxy+}/{grandchild+}

Siapkan metode HTTP

Permintaan metode API dienkapsulasi oleh sumber daya Metode API Gateway. Untuk mengatur permintaan metode, Anda harus terlebih dahulu membuat instance Method sumber daya, menyetel setidaknya metode HTTP dan jenis otorisasi pada metode.

Terkait erat dengan sumber daya proxy, API Gateway mendukung metode HTTPANY. ANYMetode ini mewakili setiap metode HTTP yang akan disediakan pada waktu berjalan. Ini memungkinkan Anda untuk menggunakan penyiapan metode API tunggal untuk semua metode HTTP yang didukungDELETE,GET,HEAD,OPTIONS,PATCH,POST, danPUT.

Anda dapat mengatur ANY metode pada sumber daya non-proxy juga. Menggabungkan ANY metode dengan sumber daya proxy, Anda mendapatkan penyiapan metode API tunggal untuk semua metode HTTP yang didukung terhadap sumber daya API apa pun. Selain itu, backend dapat berkembang tanpa merusak pengaturan API yang ada.

Sebelum menyiapkan metode API, pertimbangkan siapa yang dapat memanggil metode tersebut. Atur jenis otorisasi sesuai dengan rencana Anda. Untuk akses terbuka, atur keNONE. Untuk menggunakan izin IAM, atur jenis otorisasi ke. AWS_IAM Untuk menggunakan fungsi otorisasi Lambda, setel properti ini ke. CUSTOM Untuk menggunakan kumpulan pengguna Amazon Cognito, setel jenis otorisasi ke. COGNITO_USER_POOLS

Perintah put-method berikut membuat permintaan metode untuk ANY kata kerja menggunakan izin IAM untuk mengontrol aksesnya.

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method ANY \
    --authorization-type AWS_IAM

Untuk membuat permintaan metode API dengan jenis otorisasi yang berbeda, lihatSiapkan otorisasi permintaan metode.

Siapkan parameter permintaan metode

Parameter permintaan metode adalah cara bagi klien untuk menyediakan data input atau konteks eksekusi yang diperlukan untuk menyelesaikan permintaan metode. Parameter metode dapat berupa parameter jalur, header, atau parameter string kueri. Sebagai bagian dari pengaturan permintaan metode, Anda harus mendeklarasikan parameter permintaan yang diperlukan agar tersedia untuk klien. Untuk integrasi non-proxy, Anda dapat menerjemahkan parameter permintaan ini ke formulir yang kompatibel dengan persyaratan backend.

Misalnya, untuk permintaan GET /pets/{petId} metode, variabel {petId} jalur adalah parameter permintaan yang diperlukan. Anda dapat mendeklarasikan parameter jalur ini saat memanggil put-method perintah. AWS CLI Perintah put-method berikut menciptakan metode dengan parameter path yang diperlukan:

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id rjkmth \
    --http-method GET \
    --authorization-type "NONE" \
    --request-parameters method.request.path.petId=true

Jika parameter tidak diperlukan, Anda dapat mengaturnya ke false dalamrequest-parameters. Misalnya, jika GET /pets metode menggunakan parameter string kueri opsional daritype, dan parameter header opsionalage, Anda dapat mendeklarasikannya menggunakan perintah put-method berikut:

aws apigateway put-method --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method GET \
    --authorization-type "NONE" \
    --request-parameters method.request.querystring.type=false,method.request.header.age=false

Alih-alih formulir singkat ini, Anda dapat menggunakan string JSON untuk mengatur nilairequest-parameters:

'{"method.request.querystring.type":false,"method.request.header.age":false}'

Dengan pengaturan ini, klien dapat menanyakan hewan peliharaan berdasarkan jenis:

GET /pets?type=dog

Dan klien dapat menanyakan anjing-anjingnya yang masih kecil sebagai berikut:

GET /pets?type=dog
age:puppy

Untuk informasi tentang cara memetakan parameter permintaan metode ke parameter permintaan integrasi, lihatIntegrasi untuk REST API di API Gateway.

Siapkan model permintaan metode

Untuk metode API yang dapat mengambil data input dalam payload, Anda dapat menggunakan model. Sebuah model diekspresikan dalam skema JSON draft 4 dan menjelaskan struktur data dari badan permintaan. Dengan model, klien dapat menentukan bagaimana membangun payload permintaan metode sebagai input. Lebih penting lagi, API Gateway menggunakan model untuk memvalidasi permintaan, menghasilkan SDK, dan menginisialisasi template pemetaan untuk menyiapkan integrasi di konsol API Gateway. Untuk informasi tentang cara membuat model, lihat Memahami model data.

Tergantung pada jenis konten, payload metode dapat memiliki format yang berbeda. Sebuah model diindeks terhadap jenis media dari muatan yang diterapkan. API Gateway menggunakan header Content-Type permintaan untuk menentukan jenis konten. Untuk mengatur model permintaan metode, tambahkan pasangan kunci-nilai "media-type":"model-name" format ke requestModels peta saat memanggil perintah. AWS CLI put-method

Untuk menggunakan model yang sama terlepas dari jenis konten, tentukan $default sebagai kunci.

Misalnya, untuk menyetel model pada payload JSON dari permintaan POST /pets metode API PetStore contoh, Anda dapat menggunakan perintah put-method berikut:

aws apigateway put-method \
    --rest-api-id vaz7da96z6 \
    --resource-id 6sxz2j \
    --http-method POST \
    --authorization-type "NONE" \
    --request-models '{"application/json":"petModel"}'

Di sini, petModel adalah nilai name properti dari Modelsumber daya yang menggambarkan hewan peliharaan. Definisi skema yang sebenarnya dinyatakan sebagai nilai string JSON dari schemaproperti sumber daya. Model

Di Java, atau SDK lain yang diketik kuat, dari API, data input dilemparkan sebagai petModel kelas yang berasal dari definisi skema. Dengan model permintaan, data input dalam SDK yang dihasilkan dilemparkan ke Empty kelas, yang berasal dari Empty model default. Dalam hal ini, klien tidak dapat membuat instance kelas data yang benar untuk memberikan input yang diperlukan.

Siapkan otorisasi permintaan metode

Untuk mengontrol siapa yang dapat memanggil metode API, Anda dapat mengonfigurasi jenis otorisasi pada metode. Anda dapat menggunakan jenis ini untuk memberlakukan salah satu otorisasi yang didukung, termasuk peran dan kebijakan IAM (AWS_IAM), kumpulan pengguna Amazon Cognito ()COGNITO_USER_POOLS, atau pemberi otorisasi Lambda (). CUSTOM

Untuk menggunakan izin IAM untuk mengotorisasi akses ke metode API, setel properti authorization-type input ke. AWS_IAM Saat Anda menyetel opsi ini, API Gateway memverifikasi tanda tangan pemanggil berdasarkan kredensional pemanggil. Jika pengguna terverifikasi memiliki izin untuk memanggil metode, ia menerima permintaan tersebut. Jika tidak, ia menolak permintaan dan pemanggil menerima respons kesalahan yang tidak sah. Panggilan ke metode tidak berhasil kecuali pemanggil memiliki izin untuk memanggil metode API. Kebijakan IAM berikut memberikan izin kepada pemanggil untuk memanggil metode API apa pun yang dibuat dalam metode yang sama: Akun AWS

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": "arn:aws:execute-api:*:*:*"
        }
    ]
}

Untuk informasi selengkapnya, lihat Kontrol akses ke REST API dengan izin IAM.

Saat ini, Anda hanya dapat memberikan kebijakan ini kepada pengguna, grup, dan peran dalam pemilik API Akun AWS. Pengguna dari yang berbeda Akun AWS dapat memanggil metode API hanya jika diizinkan untuk mengambil peran dalam pemilik API Akun AWS dengan izin yang diperlukan untuk memanggil execute-api:Invoke tindakan. Untuk informasi tentang izin lintas akun, lihat Menggunakan Peran IAM.

Anda dapat menggunakan AWS CLI, AWS SDK, atau klien REST API, seperti Postman, yang mengimplementasikan penandatanganan Signature Version 4 (SigV4).

Untuk menggunakan otorisasi Lambda untuk mengotorisasi akses ke metode API, setel properti authorization-type input ke CUSTOM dan setel properti authorizer-idinput ke nilai properti dari otorisasi Lambda yang sudah ada. id Authorizer Lambda yang direferensikan dapat dari TOKEN tipe atau. REQUEST Untuk informasi tentang membuat otorisasi Lambda, lihat. Gunakan otorisasi API Gateway Lambda

Untuk menggunakan kumpulan pengguna Amazon Cognito untuk mengotorisasi akses ke metode API, setel properti authorization-type input ke COGNITO_USER_POOLS dan setel properti authorizer-idinput ke nilai idproperti COGNITO_USER_POOLS otorisasi yang telah dibuat. Untuk informasi tentang membuat otorisasi kumpulan pengguna Amazon Cognito, lihat. Kontrol akses ke REST API menggunakan kumpulan pengguna Amazon Cognito sebagai otorisasi

Siapkan validasi permintaan metode

Anda dapat mengaktifkan validasi permintaan saat menyiapkan permintaan metode API. Anda harus terlebih dahulu membuat validator permintaan. create-request-validatorPerintah berikut membuat validator permintaan body-only.

aws apigateway create-request-validator \
    --rest-api-id 7zw9uyk9kl \
    --name bodyOnlyValidator \
    --validate-request-body  \
    --no-validate-request-parameters

Outputnya akan terlihat seperti berikut:

{
    "validateRequestParameters": false, 
    "validateRequestBody": true, 
    "id": "jgpyy6", 
    "name": "bodyOnlyValidator"
}

Anda dapat menggunakan validator permintaan ini, untuk menggunakan validasi permintaan sebagai bagian dari pengaturan permintaan metode. Perintah put-method berikut membuat permintaan metode yang mengharuskan badan permintaan masuk untuk mencocokkan PetModel dan memiliki dua parameter permintaan yang tidak diperlukan:

aws apigateway put-method \
    --rest-api-id 7zw9uyk9kl \
    --resource-id xdsvhp \
    --http-method PUT \
    --authorization-type "NONE" \
    --request-parameters '{"method.request.querystring.type": false, "method.request.querystring.page":false}' \ 
    --request-models '{"application/json":"petModel"}' \
    --request-validator-id jgpyy6

Untuk menyertakan parameter permintaan dalam validasi permintaan, Anda harus mengatur validateRequestParameters true untuk validator permintaan, dan menetapkan parameter permintaan khusus ke true dalam perintah. put-method