CloudFront Fungsi struktur acara - Amazon CloudFront
Bidang versiObjek konteksObjek penampilPermintaan objekObjek responsKode status dan badanStruktur untuk string kueri, header, atau cookieContoh objek responContoh objek acara

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:

Bidang versi

versionBidang 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 standar yang terkait dengan acara tersebut.

distributionDomainNameBidang hanya muncul ketika fungsi Anda dipanggil untuk distribusi standar.

endpoint

Nama CloudFront domain (misalnya, d111111abcdef8.cloudfront.net) dari grup koneksi yang terkait dengan acara tersebut.

endpointBidang hanya muncul ketika fungsi Anda dipanggil untuk distribusi multi-penyewa.

distributionId

ID distribusi (misalnya, EDFDVBD6 CONTOH) yang terkait dengan acara.

eventType

Jenis peristiwa, viewer-request atau viewer-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

requestObjek berisi representasi dari permintaan viewer-to-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 arequest, itu tidak dapat mengubah bidang ini. Ini adalah satu-satunya kolom hanya-baca di objek request.

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 menyertakan querystring 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 objek headers. Cookie diwakili secara terpisah dalam objek cookies.

Objek headers berisi satu kolom untuk setiap header dalam permintaan. Nama header dikonversi ke ASCII-huruf kecil di objek acara, dan nama header harus ASCII-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, jika itu adalah huruf ASCII. CloudFront Fungsi tidak menerapkan perubahan apa pun pada simbol non-ASCII dalam nama header. Misalnya, TÈst-header akan menjadi tÈst-header di dalam fungsi. Simbol È non-ASCII tidak berubah.

Kata-kata dipisahkan oleh tanda hubung ()-. Misalnya, jika kode fungsi Anda menambahkan header bernamaexample-header-name, CloudFront konversi ini ke Example-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

responseObjek berisi representasi dari respon CloudFront-to-viewer HTTP. 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 memodifikasistatusCode.

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 objek headers. Cookie diwakili secara terpisah dalam objek cookies.

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 ke Example-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 di response 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 menentukan body bidang dalam fungsi respons penampil, isi asli yang dikembalikan oleh CloudFront cache atau asal akan dikembalikan ke penampil.

Jika Anda CloudFront ingin mengembalikan badan khusus ke penampil, tentukan konten isi di data bidang, dan pengkodean badan di encoding 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, hilangkan encoding bidang data dan. CloudFront memperlakukan tubuh sebagai teks biasa dalam kasus ini.

encoding

Pengkodean untuk body konten (databidang). Satu-satunya pengodean yang valid adalah text dan base64.

Jika Anda menentukan encoding sebagai base64 tetapi tubuh tidak valid base64, CloudFront mengembalikan kesalahan.

data

bodyKonten.

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 Fungsi 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-typecontent-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.

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.

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:

  1. Jika multiValue susunan ada dan memiliki modifikasi, modifikasi tersebut akan diterapkan. Elemen pertama dalam properti value diabaikan.

  2. Jika tidak, modifikasi apa pun pada properti valueproperti 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"
    }
}

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. Ini adalah contoh pemanggilan untuk distribusi standar, dan bukan untuk distribusi multi-penyewa. Untuk distribusi multi-penyewa, endpoint bidang digunakan sebagai ganti Nilai dari distributionDomainName adalah nama CloudFront domain (misalnya, d111111abcdef8.cloudfront.net) dari endpoint grup koneksi yang terkait dengan acara tersebut.

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"
                    }
                ]
            }
        }
    }
}