Siapkan API sumber daya Siapkan HTTP metode Siapkan parameter permintaan metode Siapkan model permintaan metode Siapkan otorisasi permintaan metode Siapkan validasi permintaan metode

Siapkan permintaan metode di API Gateway

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

Membuat baru API atau memilih entitas API Sumber Daya yang ada.
Membuat sumber daya API Metode yang merupakan HTTP kata kerja spesifik pada yang baru atau yang dipilih APIResource. Tugas ini dapat dibagi lagi menjadi sub tugas berikut:
- Menambahkan HTTP metode ke permintaan metode
- Mengkonfigurasi parameter permintaan
- Mendefinisikan model untuk badan permintaan
- Memberlakukan skema otorisasi
- Mengaktifkan validasi permintaan

Anda dapat melakukan tugas-tugas ini menggunakan metode berikut:

APIKonsol gerbang
AWS CLI perintah (create-resource dan put-method)
AWS SDKfungsi (misalnya, di Node.js, createResourcedan putMethod)
APIGateway REST API (sumber daya: buat dan metode:put).

Siapkan API sumber daya

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

APIEndpoint dapat berupa nama host default atau nama domain kustom. Nama host default adalah dari format berikut:


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

Dalam format ini, {api-id} mewakili API pengenal yang dihasilkan oleh API Gateway. {region}Variabel mewakili AWS Wilayah (misalnya,us-east-1) yang Anda pilih saat membuatAPI. 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 PetStore sampel API, 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 API sumber daya, Anda memilih sumber daya yang ada sebagai induknya dan kemudian membuat sumber daya anak 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.

Dengan AWS CLI, Anda dapat memanggil get-resources perintah untuk mengetahui sumber daya mana yang API tersedia:


aws apigateway get-resources --rest-api-id <apiId> \
                             --region <region>

Hasilnya adalah daftar sumber daya yang tersedia saat ini dariAPI. Untuk PetStore sampel kamiAPI, daftar ini 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, panggil perintah berikut untuk menambahkan sumber daya anak.


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

Misalnya, untuk menambahkan makanan hewan untuk dijual di PetStore situs web, tambahkan food sumber daya ke root (/) dengan menyetel path-part ke food dan parent-id kesvzr2028x8. Hasilnya terlihat seperti berikut:


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

Gunakan 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 API pengaturan yang ada. Untuk menghindari hal ini, Anda dapat menggunakan sumber daya proxy API Gateway untuk mengekspos sekumpulan API sumber daya sekaligus.

APIGateway 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/* Nama parameter jalur serakah,proxy, dapat diganti dengan string lain dengan cara yang sama seperti Anda memperlakukan nama parameter jalur biasa.

Dengan menggunakan AWS CLI, Anda memanggil perintah berikut untuk menyiapkan sumber daya proxy di bawah root (/{proxy+}):


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

Hasilnya mirip dengan yang berikut:


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

PetStoreAPIMisalnya, 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. APIGateway hanya meneruskan apa pun yang dikirimkan klien ke backend.

Sebuah API dapat memiliki lebih dari satu sumber daya proxy. Misalnya, sumber daya proxy berikut diizinkan dalamAPI, 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.

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


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

Siapkan HTTP metode

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

Terkait erat dengan sumber daya proxy, API Gateway mendukung HTTP metodeANY. ANYMetode ini mewakili HTTP metode apa pun yang akan diberikan pada waktu berjalan. Ini memungkinkan Anda untuk menggunakan pengaturan API metode tunggal untuk semua HTTP metode yang didukung dariDELETE,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 pengaturan API metode tunggal untuk semua HTTP metode yang didukung terhadap sumber daya apa pun dari fileAPI. Selain itu, backend dapat berkembang tanpa merusak pengaturan yang ada. API

Sebelum menyiapkan API metode, pertimbangkan siapa yang dapat memanggil metode tersebut. Atur jenis otorisasi sesuai dengan rencana Anda. Untuk akses terbuka, atur keNONE. Untuk menggunakan IAM izin, setel 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

AWS CLI Perintah berikut menunjukkan cara membuat permintaan metode ANY kata kerja terhadap sumber daya tertentu (6sxz2j), menggunakan IAM izin untuk mengontrol aksesnya.


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

Untuk membuat permintaan API metode 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 Ini diilustrasikan sebagai berikut:


aws apigateway put-method --rest-api-id vaz7da96z6 \
       --resource-id rjkmth \
       --http-method GET \
       --authorization-type "NONE" \
       --region us-west-2 \
       --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 opsionaltype, dan parameter header opsionalbreed, Anda dapat mendeklarasikannya menggunakan CLI perintah berikut, dengan asumsi bahwa sumber daya adalah: /pets id 6sxz2j


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

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


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

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


GET /pets?type=dog

Dan klien dapat menanyakan anjing-anjingnya dari jenis pudel sebagai berikut:


GET /pets?type=dog
breed:poodle

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

Siapkan model permintaan metode

Untuk API metode yang dapat mengambil data input dalam muatan, Anda dapat menggunakan model. Sebuah model dinyatakan dalam JSONskema draf 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 Gateway. API 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. APIGateway 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 mengatur model pada JSON payload permintaan POST /pets metode PetStore contohAPI, Anda dapat memanggil AWS CLI perintah berikut:


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

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

Dalam Java, atau diketik kuat lainnyaSDK, dariAPI, data input dilemparkan sebagai petModel kelas yang berasal dari definisi skema. Dengan model permintaan, data input yang SDK dihasilkan dilemparkan ke dalam 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 API metode ini, Anda dapat mengonfigurasi jenis otorisasi pada metode. Anda dapat menggunakan jenis ini untuk memberlakukan salah satu otorisasi yang didukung, termasuk IAM peran dan kebijakan (AWS_IAM), kumpulan pengguna Amazon Cognito (), atau pemberi otorisasi Lambda COGNITO_USER_POOLS (). CUSTOM

Untuk menggunakan IAM izin untuk mengotorisasi akses ke API metode, atur properti authorization-type input ke. AWS_IAM Saat Anda menyetel opsi ini, API Gateway memverifikasi tanda tangan pemanggil berdasarkan kredensi 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 IAMKebijakan berikut memberikan izin kepada pemanggil untuk memanggil API metode 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 a REST API dengan IAM izin.

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

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

Untuk menggunakan otorisasi Lambda untuk mengotorisasi akses ke API metode, 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 API metode, 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 API metode. Anda harus terlebih dahulu membuat validator permintaan:


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

CLIPerintah ini membuat validator permintaan body-only. Contoh output adalah sebagai berikut:


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

Dengan validator permintaan ini, Anda dapat mengaktifkan validasi permintaan sebagai bagian dari pengaturan permintaan metode:


aws apigateway put-method \
    --rest-api-id 7zw9uyk9kl 
    --region us-west-2 
    --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 dimasukkan dalam validasi permintaan, parameter permintaan harus dinyatakan sebagai wajib. Jika parameter string kueri untuk halaman digunakan dalam validasi permintaan, request-parameters peta contoh sebelumnya harus ditentukan sebagai. '{"method.request.querystring.type": false, "method.request.querystring.page":true}'

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Metode

Siapkan respons metode