Permintaan kueri untuk Amazon EC2

Permintaan kueri adalah permintaan HTTP atau HTTPS yang menggunakan kata kerja HTTP GET atau POST dan parameter Query bernamaAction. Untuk setiap tindakan Amazon EC2 API, Anda dapat memilih apakah akan menggunakan GET atau POST. Terlepas dari kata kerja mana yang Anda pilih, data yang sama dikirim dan diterima. Untuk daftar tindakan Amazon EC2 API, lihat Tindakan.

Struktur permintaan GET

Dokumentasi Amazon EC2 menyajikan permintaan GET sebagai URL, yang dapat digunakan langsung di browser.

catatan

Karena permintaan GET adalah URL, Anda harus menyandikan URL nilai parameter. Dalam dokumentasi Amazon EC2, kami membiarkan contoh permintaan GET tidak dikodekan agar lebih mudah dibaca.

Permintaan terdiri dari yang berikut:

• Endpoint: URL yang berfungsi sebagai titik masuk untuk layanan web. Untuk informasi selengkapnya, lihat titik akhir layanan Amazon EC2.

• Tindakan: Tindakan yang ingin Anda lakukan; misalnya, gunakan RunInstances untuk meluncurkan sebuah instance.

• Parameter: Setiap parameter untuk tindakan; setiap parameter dipisahkan oleh ampersand (&).

• Versi: Versi API yang akan digunakan. Untuk Amazon EC2 API, versinya adalah 2016-11-15.

• Parameter otorisasi: Parameter otorisasi yang AWS digunakan untuk memastikan validitas dan keaslian permintaan. Amazon EC2 mendukung Signature Version 2 dan Signature Version 4. Kami merekomendasi Anda menggunakan Tanda tangan Versi 4. Untuk informasi selengkapnya, lihat Menandatangani permintaan AWS API di Panduan Pengguna IAM.

Parameter opsional berikut dapat dimasukkan dalam permintaan Anda:

• DryRun: Memeriksa apakah Anda memiliki izin yang diperlukan untuk tindakan tersebut, tanpa benar-benar membuat permintaan. Jika Anda memiliki izin yang diperlukan, permintaan akan kembaliDryRunOperation; jika tidak, ia kembaliUnauthorizedOperation.

• SecurityToken: Token keamanan sementara diperoleh melalui panggilan ke AWS Security Token Service.

Untuk informasi selengkapnya tentang parameter umum untuk permintaan API, lihat Parameter kueri umum.

Berikut ini adalah contoh permintaan yang meluncurkan instance:

https://ec2.amazonaws.com/?Action=RunInstances&ImageId=ami-2bb65342&MaxCount=3&MinCount=1&Placement.AvailabilityZone=us-east-1a&Monitoring.Enabled=true&Version=2016-11-15&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIDEXAMPLE%2F20130813%2Fus-east-1%2Fec2%2Faws4_request&X-Amz-Date=20130813T150206Z&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date&X-Amz-Signature=525d1a96c69b5549dd78dbbec8efe264102288b83ba87b7d58d4b76b71f59fd2
Content-type: application/json
host:ec2.amazonaws.com

Untuk membuat permintaan contoh ini lebih mudah dibaca, AWS dokumentasi dapat menyajikannya dalam format berikut:

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&Version=2016-11-15
&X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=AKIAIOSFODNN7EXAMPLEus-east-1%2Fec2%2Faws4_request
&X-Amz-Date=20130813T150206Z
&X-Amz-SignedHeaders=content-type%3Bhost%3Bx-amz-date
&X-Amz-Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c
Content-type: application/json
host:ec2.amazonaws.com

Baris pertama menentukan titik akhir permintaan. Setelah titik akhir adalah tanda tanya (?), yang memisahkan titik akhir dari parameter. Untuk informasi selengkapnya tentang titik akhir Amazon EC2, lihat titik akhir layanan Amazon EC2.

Parameter Action menunjukkan tindakan untuk dilakukan. Untuk daftar lengkap tindakan, lihat Tindakan. Baris yang tersisa menentukan parameter tambahan untuk permintaan tersebut.

Dalam contoh Permintaan kueri yang kami sajikan dalam dokumentasi Amazon EC2 API, kami menghilangkan header, parameter umum yang diperlukan, dan parameter otentikasi untuk memudahkan Anda fokus pada parameter tindakan. Kami menggantinya dengan string &AUTHPARAMS literal untuk mengingatkan Anda bahwa Anda harus memasukkan parameter ini dalam permintaan Anda; misalnya:

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Placement.AvailabilityZone=us-east-1a
&Monitoring.Enabled=true
&AUTHPARAMS

penting

Sebelum Anda menentukan ID kunci akses untuk Credential parameter AWSAccessKeyId atau, tinjau dan ikuti panduan dalam kredensi AWS keamanan.

Parameter kueri

Setiap permintaan Kueri harus menyertakan parameter umum yang diperlukan untuk menangani otentikasi dan pemilihan tindakan. Parameter kueri peka huruf besar/kecil.

Beberapa operasi mengambil daftar parameter. Daftar ini ditentukan menggunakan notasi param.n, di mana n adalah bilangan bulat mulai dari 1.

Contoh berikut menambahkan beberapa perangkat ke pemetaan perangkat blok menggunakan daftar BlockDeviceMapping parameter.

http://ec2.amazonaws.com/?Action=RunInstances
&ImageId.1=ami-72aa081b
...
&BlockDeviceMapping.1.DeviceName=/dev/sdj
&BlockDeviceMapping.1.Ebs.NoDevice=true
&BlockDeviceMapping.2.DeviceName=/dev/sdh
&BlockDeviceMapping.2.Ebs.VolumeSize=300
&BlockDeviceMapping.3.DeviceName=/dev/sdc
&BlockDeviceMapping.3.VirtualName=ephemeral1
&AUTHPARAMS

Kueri otentikasi API

Anda dapat mengirim permintaan Query melalui protokol HTTP atau HTTPS.

Terlepas dari protokol mana yang Anda gunakan, Anda harus menyertakan tanda tangan di setiap permintaan Kueri. Amazon EC2 mendukung Signature Version 2 dan Signature Version 4. Kami merekomendasi Anda menggunakan Tanda tangan Versi 4. Untuk informasi selengkapnya, lihat Menandatangani permintaan AWS API di Panduan Pengguna IAM.

Permintaan Signature Version 4 memungkinkan Anda untuk menentukan semua parameter otorisasi dalam satu header, misalnya:

Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Amz-Date: 20130813T150211Z
Host: ec2.amazonaws.com
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/202230813/us-east-1/ec2/aws4_request, SignedHeaders=content-type;host;x-amz-date, Signature=ced6826de92d2bdeed8f846f0bf508e8559e98e4b0194b84example54174deb456c

http://ec2.amazonaws.com/?Action=RunInstances
ImageId=ami-2bb65342
&MaxCount=3
&MinCount=1
&Monitoring.Enabled=true
&Placement.AvailabilityZone=us-east-1a
&Version=2016-11-15

Struktur respons kueri

Menanggapi permintaan Kueri, layanan mengembalikan struktur data XMLyang sesuai dengan skema XMLyang ditentukan untuk Amazon EC2. Struktur respon XHTML khusus untuk permintaan terkait. Secara umum, tipe data respons diberi nama sesuai dengan operasi yang dilakukan dan apakah tipe data adalah wadah (dapat memiliki anak). Contoh kontainer termasuk groupSet untuk grup keamanan dan keySet untuk pasangan kunci (lihat contoh berikut). Elemen item adalah anak-anak dari wadah, dan isinya bervariasi sesuai dengan peran wadah.

Setiap respons yang berhasil menyertakan ID permintaan dalam requestId elemen, dan setiap respons yang gagal menyertakan ID permintaan dalam RequestID elemen. Nilainya adalah string unik yang AWS menetapkan. Jika Anda pernah memiliki masalah dengan permintaan tertentu, AWS akan meminta ID permintaan untuk membantu memecahkan masalah. Berikut ini menunjukkan contoh respons.

<DescribeKeyPairsResponse xmlns="http://ec2.amazonaws.com/doc/2016-11-15/">
  <requestId>7a62c49f-347e-4fc4-9331-6e8eEXAMPLE</requestId>
  <keySet>
    <item>
      <keyName>gsg-keypair</keyName>
      <keyFingerprint>
         00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00
      </keyFingerprint>
    </item>
  </keySet>
</DescribeKeyPairsResponse>

Pertimbangan-pertimbangan

• Mulai 31 Juli 2024, untuk setiap tindakan Amazon EC2 API baru atau Wilayah yang baru AWS didukung, struktur data XHTML dalam tanggapan tidak akan menyertakan baris dan lekukan baru. Jika Anda menggunakan klien khusus, pastikan bahwa itu tidak bergantung pada tanggapan termasuk baris dan lekukan baru.

• Per 31 Juli 2025, struktur data XHTML dalam tanggapan tidak akan lagi menyertakan baris dan lekukan baru. Perubahan ini akan mengurangi ukuran respons. Jika Anda menggunakan klien khusus, pastikan bahwa itu tidak bergantung pada tanggapan termasuk baris dan lekukan baru.

• Urutan elemen dalam respons, termasuk yang berada dalam struktur bersarang, dapat bervariasi. Aplikasi tidak boleh berasumsi bahwa elemen muncul dalam urutan tertentu.

Paginasi

Untuk tindakan yang dapat menampilkan daftar item yang panjang, Amazon EC2 API menyertakan parameter untuk mendukung pagination:MaxResults, NextToken (input), dan nextToken (output). Dengan pagination, Anda menentukan ukuran untuk MaxResults dan kemudian setiap panggilan mengembalikan 0 ke MaxResults item dan setnextToken. Jika ada item tambahan untuk diulang, nextToken adalah non-null dan Anda dapat menentukan nilainya dalam NextToken parameter panggilan berikutnya untuk mendapatkan set item berikutnya. Dengan pagination, Anda terus memanggil tindakan sampai nextToken nol, bahkan jika Anda menerima kurang dari MaxResults item, termasuk item nol.

Jika Anda memanggil tindakan mendeskripsikan API dengan daftar ID danMaxResults, permintaan gagal dengan kesalahan tersebutInvalidParameterCombination.

Kami menyarankan Anda menggunakan pagination saat menggunakan tindakan deskripsikan yang berpotensi mengembalikan sejumlah besar hasil, sepertiDescribeInstances. Menggunakan pagination membatasi jumlah item yang dikembalikan dan waktu yang diperlukan untuk panggilan ini untuk kembali.

Untuk informasi selengkapnya, lihat Pagination di Panduan Pengembang Amazon EC2.

Mencegah permintaan melalui HTTP

Jika beban kerja Anda tidak mengharuskan Anda untuk menggunakan HTTP, kami sarankan Anda menghindari menggunakannya untuk mencegah transmisi dan penerimaan data yang tidak terenkripsi, dan untuk menggunakan HTTPS sebagai gantinya. Anda dapat menggunakan kunci kondisi IAM aws:SecureTransportglobal dalam kebijakan IAM Anda untuk mencegah pengguna mengirim permintaan melalui HTTP.

Contoh kebijakan berikut mencegah pengguna mengirim permintaan melalui HTTP.

{
    "Statement": [
        {
            "Sid": "AllowAllEC2HttpsRequests",
            "Effect": "Allow",
            "Action": "ec2:*",
            "Resource": "*",
            "Condition": {
                "StringEqualsIgnoreCase": {
                    "aws:SecureTransport": "true"
                }
            }
        }
    ]
}