Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
CloudFront Fungsi struktur acara
CloudFront Fungsi meneruskan event
objek ke kode fungsi Anda sebagai input ketika menjalankan fungsi. Saat Anda menguji fungsi, Anda membuat objek event
dan meneruskannya ke fungsi Anda. Saat Anda membuat objek event
untuk menguji fungsi, Anda dapat menghilangkan kolom distributionDomainName
, distributionId
, dan requestId
dalam objek context
. Pastikan bahwa nama header adalah huruf kecil, yang selalu terjadi pada event
objek yang diteruskan CloudFront Functions ke fungsi Anda dalam produksi.
Berikut ini menunjukkan gambaran umum struktur objek peristiwa ini.
{ "version": "1.0", "context": { <context object> }, "viewer": { <viewer object> }, "request": { <request object> }, "response": { <response object> } }
Untuk informasi selengkapnya, lihat topik berikut.
Topik
Bidang versi
version
Bidang berisi string yang menentukan versi objek acara CloudFront Functions. Versi saat ini adalah 1.0
.
Objek konteks
Objek context
berisi informasi kontekstual tentang peristiwa tersebut. Ini mencakup kolom-kolom berikut:
distributionDomainName
-
Nama CloudFront domain (misalnya, d111111abcdef8.cloudfront.net) dari distribusi yang terkait dengan acara tersebut.
distributionId
-
ID distribusi (misalnya, EDFDVBD6EXAMPLE) yang terkait dengan acara tersebut.
eventType
-
Jenis peristiwa,
viewer-request
atauviewer-response
. requestId
-
String yang secara unik mengidentifikasi CloudFront permintaan (dan respons terkait).
Objek penampil
Objek viewer
berisi kolom ip
yang nilainya adalah alamat IP penampil (klien) yang mengirim permintaan. Jika perminttaan penampil melewati proksi HTTP atau penyeimbang beban, nilainya adalah alamat IP proksi atau load balancer.
Permintaan objek
request
Objek berisi representasi permintaan pemirsa ke- CloudFront HTTP. Dalam event
objek yang diteruskan ke fungsi Anda, request
objek mewakili permintaan aktual yang CloudFront diterima dari penampil.
Jika kode fungsi Anda mengembalikan request
objek ke CloudFront, itu harus menggunakan struktur yang sama.
Objek request
berisi kolom-kolom berikut:
method
-
Metode HTTP permintaan. Jika kode fungsi Anda mengembalikan a
request
, itu tidak dapat memodifikasi bidang ini. Ini adalah satu-satunya kolom hanya-baca di objekrequest
. uri
-
Jalur relatif objek yang diminta.
catatan
Jika fungsi Anda mengubah
uri
nilai, berikut ini berlaku:-
Nilai
uri
baru harus dimulai dengan garis miring ke depan (/
). -
Saat fungsi mengubah nilai
uri
, fungsi tersebut mengubah objek yang diminta oleh penampil. -
Saat fungsi mengubah
uri
nilainya, fungsi tersebut tidak mengubah perilaku cache untuk permintaan atau asal tempat permintaan asal dikirim.
-
querystring
-
Sebuah objek yang mewakili string kueri dalam permintaan. Jika permintaan tidak menyertakan string kueri,
request
objek masih menyertakanquerystring
objek kosong.Objek
querystring
berisi satu kolom untuk setiap parameter string kueri dalam permintaan. headers
-
Sebuah objek yang mewakili string kueri dalam permintaan. Jika permintaan berisi header
Cookie
, header tersebut bukan bagian dari objekheaders
. Cookie diwakili secara terpisah dalam objekcookies
.Objek
headers
berisi satu kolom untuk setiap header dalam permintaan. Nama header dikonversi ke huruf kecil di objek acara, dan nama header harus huruf kecil ketika ditambahkan oleh kode fungsi Anda. Ketika CloudFront Fungsi mengubah objek acara kembali ke permintaan HTTP, huruf pertama dari setiap kata dalam nama header dikapitalisasi. Kata-kata dipisahkan oleh tanda hubung ()-
. Misalnya, jika kode fungsi Anda menambahkan header bernamaexample-header-name
, CloudFront konversi ini keExample-Header-Name
dalam permintaan HTTP. cookies
-
Sebuah objek yang mewakili cookie dalam permintaan (header
Cookie
).Objek
cookies
berisi satu kolom untuk setiap cookie dalam permintaan.
Untuk informasi selengkapnya tentang struktur string kueri, header, dan cookie, lihat Struktur untuk string kueri, header, atau cookie.
Misalnya, objek event
, lihat Contoh objek acara.
Objek respons
response
Objek berisi representasi dari respon HTTP CloudFront -to-viewer. Dalam event
objek yang diteruskan ke fungsi Anda, response
objek mewakili respons CloudFront aktual terhadap permintaan penampil.
Jika kode fungsi Anda mengembalikan objek response
, kode tersebut harus menggunakan struktur yang sama.
Objek response
berisi kolom-kolom berikut:
statusCode
-
Kode status HTTP dari respons. Nilai ini adalah bilangan bulat, bukan string.
Fungsi Anda dapat menghasilkan atau memodifikasi
statusCode
. statusDescription
-
Deskripsi status HTTP untuk respons. Jika kode fungsi Anda menghasilkan respons, kolom ini menjadi opsional.
headers
-
Sebuah objek yang merepresentasikan header HTTP dalam respons. Jika respons berisi header
Set-Cookie
, header tersebut bukan bagian dari objekheaders
. Cookie diwakili secara terpisah dalam objekcookies
.Objek
headers
berisi satu kolom untuk setiap header dalam respons. Nama header dikonversi ke huruf kecil di objek acara, dan nama header harus huruf kecil ketika ditambahkan oleh kode fungsi Anda. Ketika CloudFront Fungsi mengubah objek acara kembali menjadi respons HTTP, huruf pertama dari setiap kata dalam nama header dikapitalisasi. Kata-kata dipisahkan oleh tanda hubung ()-
. Misalnya, jika kode fungsi Anda menambahkan header bernamaexample-header-name
, CloudFront konversi ini keExample-Header-Name
dalam respon HTTP. cookies
-
Sebuah objek yang mewakili cookie dalam respons (header
Set-Cookie
).Objek
cookies
berisi satu kolom untuk setiap cookie dalam respons. body
-
Menambahkan
body
bidang adalah opsional, dan itu tidak akan ada diresponse
objek kecuali Anda menentukannya dalam fungsi Anda. Fungsi Anda tidak memiliki akses ke badan asli yang dikembalikan oleh CloudFront cache atau asal. Jika Anda tidak menentukanbody
bidang dalam fungsi respons penampil, isi asli yang dikembalikan oleh CloudFront cache atau asal akan dikembalikan ke penampil.Jika Anda CloudFront ingin mengembalikan badan kustom ke penampil, tentukan isi isi di
data
bidang, dan pengkodean badan diencoding
bidang. Anda dapat menentukan encoding sebagai plain text ("encoding": "text"
) atau sebagai Base64-encoded content ()."encoding": "base64"
Sebagai pintasan, Anda juga dapat menentukan isi isi langsung di
body
bidang ("body": "<specify the body content here>"
). Ketika Anda melakukan ini, hilangkanencoding
bidangdata
dan. CloudFront memperlakukan tubuh sebagai teks biasa dalam kasus ini.encoding
-
Pengkodean untuk
body
konten (data
bidang). Satu-satunya pengodean yang valid adalahtext
danbase64
.Jika Anda menentukan
encoding
sebagaibase64
tetapi tubuh tidak valid base64, CloudFront mengembalikan kesalahan. data
-
body
Konten.
Untuk informasi selengkapnya tentang kode status dan isi isi yang dimodifikasi, lihatKode status dan badan.
Untuk informasi selengkapnya tentang struktur header dan cookie, lihat Struktur untuk string kueri, header, atau cookie.
Misalnya, objek response
, lihat Contoh objek respon.
Kode status dan badan
Dengan CloudFront Fungsi, Anda dapat memperbarui kode status respons penampil, mengganti seluruh badan respons dengan yang baru, atau menghapus badan respons. Beberapa skenario umum untuk memperbarui respons penampil setelah mengevaluasi aspek respons dari CloudFront cache atau asal termasuk yang berikut:
-
Mengubah status untuk menyetel kode status HTTP 200 dan membuat konten badan statis untuk kembali ke penampil.
-
Mengubah status untuk menetapkan kode status HTTP 301 atau 302 untuk mengarahkan pengguna ke situs web lain.
-
Memutuskan apakah akan melayani atau menjatuhkan tubuh respons pemirsa.
catatan
Jika asal mengembalikan kesalahan HTTP 400 ke atas, CloudFront Fungsi tidak akan berjalan. Untuk mengetahui informasi selengkapnya, lihat Pembatasan pada semua fungsi edge.
Saat Anda bekerja dengan respons HTTP, CloudFront Functions tidak memiliki akses ke badan respons. Anda dapat mengganti isi isi dengan mengaturnya ke nilai yang diinginkan, atau Anda dapat menghapus tubuh dengan mengatur nilai menjadi kosong. Jika Anda tidak memperbarui bidang isi dalam fungsi Anda, isi asli yang dikembalikan oleh CloudFront cache atau asal dikembalikan ke penampil.
Tip
Saat menggunakan CloudFront Functions untuk mengganti body, pastikan untuk menyelaraskan header yang sesuai, seperticontent-encoding
,, atau content-type
content-length
, ke isi isi baru.
Misalnya, jika CloudFront asal atau cache kembali content-encoding:
gzip
tetapi fungsi respons penampil menyetel isi teks biasa, fungsi tersebut juga perlu mengubah content-encoding
dan content-type
header yang sesuai.
Jika CloudFront Fungsi Anda dikonfigurasi untuk mengembalikan kesalahan HTTP 400 atau lebih tinggi, penampil Anda tidak akan melihat halaman kesalahan kustom yang telah Anda tentukan untuk kode status yang sama.
Struktur untuk string kueri, header, atau cookie
String kueri, header, dan cookie berbagi struktur yang sama. String kueri dapat muncul dalam permintaan. Header muncul dalam permintaan dan tanggapan. Cookie muncul dalam permintaan dan tanggapan.
Setiap string kueri, header, atau cookie adalah kolom yang unik dalam objek querystring
,headers
, atau cookies
induk. Nama bidang adalah nama string kueri, header, atau cookie. Setiap kolom berisi properti value
dengan nilai string kueri, header, atau cookie.
Daftar Isi
Nilai string kueri atau objek string kueri
Sebuah fungsi dapat mengembalikan nilai string query selain objek string query. Nilai string kueri dapat digunakan untuk mengatur parameter string kueri dalam urutan kustom apa pun.
contoh Contoh
Untuk memodifikasi string kueri dalam kode fungsi Anda, gunakan kode seperti berikut ini.
var request = event.request; request.querystring = 'ID=42&Exp=1619740800&TTL=1440&NoValue=&querymv=val1&querymv=val2,val3';
Pertimbangan khusus untuk header
Hanya untuk header, nama header dikonversi ke huruf kecil di objek acara, dan nama header harus huruf kecil ketika ditambahkan oleh kode fungsi Anda. Ketika CloudFront Fungsi mengubah objek acara kembali menjadi permintaan atau respons HTTP, huruf pertama dari setiap kata dalam nama header dikapitalisasi. Kata-kata dipisahkan oleh tanda hubung ()-
. Misalnya, jika kode fungsi Anda menambahkan header bernamaexample-header-name
, CloudFront mengonversinya menjadi Example-Header-Name
permintaan atau respons HTTP.
contoh Contoh
Pertimbangkan Host
header berikut dalam permintaan HTTP.
Host: video.example.com
Header ini direpresentasikan sebagai berikut dalam objek request
:
"headers": { "host": { "value": "video.example.com" } }
Untuk mengakses header Host
dalam kode fungsi Anda, gunakan kode seperti berikut:
var request = event.request; var host = request.headers.host.value;
Untuk menambah atau memodifikasi header dalam kode fungsi Anda, gunakan kode seperti berikut (kode ini menambahkan header bernama X-Custom-Header
dengan nilai example value
):
var request = event.request; request.headers['x-custom-header'] = {value: 'example value'};
Duplikasi string kueri, header, dan cookie (multiValue
susunan)
Permintaan atau respons HTTP dapat berisi lebih dari satu string kueri, header, atau cookie dengan nama yang sama. Dalam hal ini, string kueri, header, atau cookie duplikat dikumpulkan dalam satu kolom di objek request
atau response
, tetapi kolom ini berisi properti tambahan bernama multiValue
. Properti multiValue
berisi susunan dengan nilai-nilai masing-masing string kueri, header, atau cookie duplikat.
contoh Contoh
Pertimbangkan permintaan HTTP dengan Accept
header berikut.
Accept: application/json Accept: application/xml Accept: text/html
Header ini direpresentasikan sebagai berikut dalam request
objek.
"headers": { "accept": { "value": "application/json", "multiValue": [ { "value": "application/json" }, { "value": "application/xml" }, { "value": "text/html" } ] } }
catatan
Nilai header pertama (dalam hal ini,application/json
) diulang di kedua multiValue
properti value
dan. Ini memungkinkan Anda untuk mengakses semua nilai dengan perulangan melalui multiValue
susunan.
Jika kode fungsi Anda memodifikasi string kueri, header, atau cookie yang memiliki multiValue
array, CloudFront Fungsi menggunakan aturan berikut untuk menerapkan perubahan:
-
Jika
multiValue
susunan ada dan memiliki modifikasi, modifikasi tersebut akan diterapkan. Elemen pertama dalam propertivalue
diabaikan. -
Jika tidak, modifikasi apa pun pada properti
value
properti diterapkan, dan nilai berikutnya (jika ada) tetap sama.
Properti multiValue
digunakan hanya ketika permintaan HTTP atau respons berisi string kueri, header, atau cookie duplikat dengan nama yang sama, seperti yang ditunjukkan dalam contoh sebelumnya. Namun, jika ada beberapa nilai dalam satu string kueri, header, atau cookie, properti multiValue
tidak akan digunakan.
contoh Contoh
Pertimbangkan permintaan dengan satu Accept
header yang berisi tiga nilai.
Accept: application/json, application/xml, text/html
Header ini direpresentasikan sebagai berikut dalam request
objek.
"headers": { "accept": { "value": "application/json, application/xml, text/html" } }
Atribut cookie
Dalam header Set-Cookie
dalam respons HTTP, header berisi pasangan nama-nilai untuk cookie dan opsi satu set atribut dipisahkan oleh titik koma.
contoh Contoh
Set-Cookie: cookie1=val1; Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT
Di objek response
, atribut ini direpresentasikan dalam properti attributes
dari kolom cookie. Sebagai contoh, header Set-Cookie
sebelumnya direpresentasikan sebagai berikut:
"cookie1": { "value": "val1", "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT" }
Contoh objek respon
Contoh berikut menunjukkan response
objek - output dari fungsi respons penampil - di mana tubuh telah digantikan oleh fungsi respons penampil.
{ "response": { "statusCode": 200, "statusDescription": "OK", "headers": { "date": { "value": "Mon, 04 Apr 2021 18:57:56 GMT" }, "server": { "value": "gunicorn/19.9.0" }, "access-control-allow-origin": { "value": "*" }, "access-control-allow-credentials": { "value": "true" }, "content-type": { "value": "text/html" }, "content-length": { "value": "86" } }, "cookies": { "ID": { "value": "id1234", "attributes": "Expires=Wed, 05 Apr 2021 07:28:00 GMT" }, "Cookie1": { "value": "val1", "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT", "multiValue": [ { "value": "val1", "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT" }, { "value": "val2", "attributes": "Path=/cat; Domain=example.com; Expires=Wed, 10 Jan 2021 07:28:00 GMT" } ] } }, // Adding the body field is optional and it will not be present in the response object // unless you specify it in your function. // Your function does not have access to the original body returned by the CloudFront // cache or origin. // If you don't specify the body field in your viewer response function, the original // body returned by the CloudFront cache or origin is returned to viewer. "body": { "encoding": "text", "data": "<!DOCTYPE html><html><body><p>Here is your custom content.</p></body></html>" } } }
Contoh objek acara
Contoh berikut menunjukkan objek event
lengkap.
catatan
Objek event
adalah masukan untuk fungsi Anda. Fungsi Anda hanya mengembalikan hanya objek request
atau response
, bukan objek event
lengkap.
{ "version": "1.0", "context": { "distributionDomainName": "d111111abcdef8.cloudfront.net", "distributionId": "EDFDVBD6EXAMPLE", "eventType": "viewer-response", "requestId": "EXAMPLEntjQpEXAMPLE_SG5Z-EXAMPLEPmPfEXAMPLEu3EqEXAMPLE==" }, "viewer": {"ip": "198.51.100.11"}, "request": { "method": "GET", "uri": "/media/index.mpd", "querystring": { "ID": {"value": "42"}, "Exp": {"value": "1619740800"}, "TTL": {"value": "1440"}, "NoValue": {"value": ""}, "querymv": { "value": "val1", "multiValue": [ {"value": "val1"}, {"value": "val2,val3"} ] } }, "headers": { "host": {"value": "video.example.com"}, "user-agent": {"value": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:83.0) Gecko/20100101 Firefox/83.0"}, "accept": { "value": "application/json", "multiValue": [ {"value": "application/json"}, {"value": "application/xml"}, {"value": "text/html"} ] }, "accept-language": {"value": "en-GB,en;q=0.5"}, "accept-encoding": {"value": "gzip, deflate, br"}, "origin": {"value": "https://website.example.com"}, "referer": {"value": "https://website.example.com/videos/12345678?action=play"}, "cloudfront-viewer-country": {"value": "GB"} }, "cookies": { "Cookie1": {"value": "value1"}, "Cookie2": {"value": "value2"}, "cookie_consent": {"value": "true"}, "cookiemv": { "value": "value3", "multiValue": [ {"value": "value3"}, {"value": "value4"} ] } } }, "response": { "statusCode": 200, "statusDescription": "OK", "headers": { "date": {"value": "Mon, 04 Apr 2021 18:57:56 GMT"}, "server": {"value": "gunicorn/19.9.0"}, "access-control-allow-origin": {"value": "*"}, "access-control-allow-credentials": {"value": "true"}, "content-type": {"value": "application/json"}, "content-length": {"value": "701"} }, "cookies": { "ID": { "value": "id1234", "attributes": "Expires=Wed, 05 Apr 2021 07:28:00 GMT" }, "Cookie1": { "value": "val1", "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT", "multiValue": [ { "value": "val1", "attributes": "Secure; Path=/; Domain=example.com; Expires=Wed, 05 Apr 2021 07:28:00 GMT" }, { "value": "val2", "attributes": "Path=/cat; Domain=example.com; Expires=Wed, 10 Jan 2021 07:28:00 GMT" } ] } } } }