API tingkat rendah DynamoDB

API tingkat rendah Amazon DynamoDB adalah antarmuka tingkat protokol untuk DynamoDB. Pada tingkat ini, setiap permintaan HTTP(S) harus diformat dengan benar dan membawa tanda tangan digital yang valid.

AWS SDK membuat permintaan API DynamoDB tingkat rendah atas nama Anda dan memproses respons dari DynamoDB. Ini memungkinkan Anda berfokus pada logika aplikasi Anda, bukan detail tingkat rendah. Namun, Anda masih bisa mendapatkan keuntungan dari pengetahuan dasar tentang bagaimana DynamoDB API tingkat rendah bekerja.

Untuk informasi selengkapnya tentang DynamoDB API, lihat Referensi Amazon DynamoDB API.

catatan

DynamoDB Streams memiliki API tingkat rendah sendiri, yang terpisah dari DynamoDB dan didukung penuh oleh SDK. AWS

Untuk informasi selengkapnya, lihat Tangkapan data perubahan DynamoDB Streams. Untuk DynamoDB Streams API tingkat rendah, lihat Referensi Amazon DynamoDB Streams API.

DynamoDB API tingkat rendah JavaScript menggunakan Object Notation (JSON) sebagai format protokol kawat. JSON menyajikan data dalam hierarki sehingga nilai data dan struktur data disampaikan secara bersamaan. Pasangan nama-nilai ditentukan dalam format name:value. Hierarki data ditentukan oleh tanda kurung berisi pasangan nama-nilai.

DynamoDB menggunakan JSON hanya sebagai protokol transportasi, bukan sebagai format penyimpanan. AWS SDK menggunakan JSON untuk mengirim data ke DynamoDB, dan DynamoDB merespons dengan JSON. DynamoDB tidak menyimpan data terus-menerus dalam format JSON.

catatan

Untuk informasi selengkapnya tentang JSON, lihat Memperkenalkan JSON pada situs web JSON.org.

Format permintaan

API tingkat rendah DynamoDB menerima permintaan POST HTTP(S) sebagai masukan. AWS SDK membangun permintaan ini untuk Anda.

Misalkan Anda memiliki tabel bernama Pets, dengan skema kunci yang terdiri dari AnimalType (kunci partisi) dan Name (kunci urutan). Kedua atribut ini berjenis string. Untuk mengambil item dariPets, AWS SDK membuat permintaan berikut.

POST / HTTP/1.1
Host: dynamodb.<region>.<domain>;
Accept-Encoding: identity
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.0
Authorization: AWS4-HMAC-SHA256 Credential=<Credential>, SignedHeaders=<Headers>, Signature=<Signature>
X-Amz-Date: <Date> 
X-Amz-Target: DynamoDB_20120810.GetItem

{
    "TableName": "Pets",
    "Key": {
        "AnimalType": {"S": "Dog"},
        "Name": {"S": "Fido"}
    }
}

Perhatikan hal berikut tentang permintaan ini:

• Header Authorization berisi informasi yang diperlukan untuk DynamoDB guna mengautentikasi permintaan. Untuk informasi selengkapnya, lihat Menandatangani permintaan AWS API dan proses penandatanganan Versi Tanda Tangan 4 di bagian Referensi Umum Amazon Web Services.

• Header X-Amz-Target berisi nama operasi DynamoDB: GetItem. (Ini juga disertai dengan versi API tingkat rendah, dalam hal ini 20120810.)

• Muatan (isi) permintaan mengandungi parameter untuk operasi, dalam format JSON. Untuk operasi GetItem, parameternya adalah TableName dan Key.

Format respons

Setelah menerima permintaan, DynamoDB memprosesnya dan mengembalikan respons. Untuk permintaan yang ditunjukkan sebelumnya, muatan respons HTTP(S) berisi hasil dari operasi, seperti yang ditunjukkan pada contoh berikut.

HTTP/1.1 200 OK
x-amzn-RequestId: <RequestId>
x-amz-crc32: <Checksum>
Content-Type: application/x-amz-json-1.0
Content-Length: <PayloadSizeBytes>
Date: <Date>
{
    "Item": {
        "Age": {"N": "8"},
        "Colors": {
            "L": [
                {"S": "White"},
                {"S": "Brown"},
                {"S": "Black"}
            ]
        },
        "Name": {"S": "Fido"},
        "Vaccinations": {
            "M": {
                "Rabies": {
                    "L": [
                        {"S": "2009-03-17"},
                        {"S": "2011-09-21"},
                        {"S": "2014-07-08"}
                    ]
                },
                "Distemper": {"S": "2015-10-13"}
            }
        },
        "Breed": {"S": "Beagle"},
        "AnimalType": {"S": "Dog"}
    }
}

Pada titik ini, AWS SDK mengembalikan data respons ke aplikasi Anda untuk diproses lebih lanjut.

catatan

Jika DynamoDB tidak dapat memproses permintaan, DynamoDB akan mengembalikan kode kesalahan HTTP dan pesan. AWS SDK menyebarkannya untuk aplikasi Anda dalam bentuk pengecualian. Untuk informasi selengkapnya, lihat Penanganan kesalahan dengan DynamoDB.

Deskriptor jenis data

Protokol DynamoDB API tingkat rendah membutuhkan setiap atribut untuk disertai dengan deskriptor jenis data. Deskriptor jenis data adalah token yang memberi tahu DynamoDB cara menafsirkan setiap atribut.

Contoh di Format permintaan dan Format respons menunjukkan contoh bagaimana deskriptor jenis data digunakan. Permintaan GetItem menentukan S untuk atribut skema kunci Pets (AnimalType dan Name), yang berjenis string. Respons GetItem berisi item Pets dengan atribut jenis string (S), number (N), map (M), dan list (L).

Berikut ini adalah daftar lengkap deskriptor jenis data DynamoDB:

• S – String

• N – Nomor

• B – Biner

• BOOL – Boolean

• NULL – Null

• M – Peta

• L – Daftar

• SS – Set String

• NS – Set Nomor

• BS – Set Biner

catatan

Untuk deskripsi mendetail tentang jenis data DynamoDB, lihat Jenis Data.

Data numerik

Bahasa pemrograman yang berbeda menawarkan tingkat dukungan yang berbeda untuk JSON. Dalam beberapa kasus, Anda mungkin memutuskan untuk menggunakan pustaka pihak ketiga untuk memvalidasi dan menguraikan dokumen JSON.

Beberapa pustaka pihak ketiga membangun jenis angka JSON, menyediakan jenisnya sendiri seperti int, long, atau double. Namun, jenis data angka asli di DynamoDB tidak memetakan persis untuk jenis data lainnya, sehingga perbedaan jenis ini dapat menyebabkan konflik. Selain itu, banyak pustaka JSON tidak menangani nilai numerik presisi tetap, dan secara otomatis menyimpulkan jenis data ganda untuk urutan digit yang berisi titik desimal.

Untuk mengatasi masalah ini, DynamoDB menyediakan jenis numerik tunggal tanpa kehilangan data. Untuk menghindari konversi implisit yang tidak diinginkan ke nilai ganda, DynamoDB menggunakan string untuk transfer data nilai numerik. Pendekatan ini memberikan fleksibilitas untuk memperbarui nilai atribut sekaligus mempertahankan semantik pengurutan yang tepat, seperti menempatkan nilai "01", "2", dan "03" dalam urutan yang tepat.

Jika presisi angka penting untuk aplikasi, Anda harus mengonversi nilai numerik untuk string tersebut sebelum meneruskannya ke DynamoDB.

Data biner

DynamoDB mendukung atribut binari. Namun, JSON tidak secara native mendukung data biner pengodean. Untuk mengirim data biner dalam permintaan, Anda perlu untuk mengodekannya dalam format base64. Setelah menerima permintaan, DynamoDB mengodekan data base64 kembali ke biner.

Skema pengodean base64 yang digunakan oleh DynamoDB dijelaskan di RFC 4648 di situs web Internet Engineering Task Force (IETF).