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 Functions ke CloudFront 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

Bid version ang 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:

Struktur acara koneksi

Fungsi koneksi menerima struktur peristiwa yang berbeda dari fungsi penampil. Untuk informasi terperinci tentang struktur peristiwa koneksi dan format respons, lihatMengaitkan Fungsi CloudFront Koneksi.

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

Ob request jek berisi representasi permintaan pemirsa-ke-HTTP. CloudFront 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 ini.

Objek request berisi kolom-kolom berikut:

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

Ob response jek berisi representasi respons 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:

Untuk informasi selengkapnya tentang kode status dan konten 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 respons.

Kode status dan badan

Dengan CloudFront Functions, Anda dapat memperbarui kode status respons penampil, mengganti seluruh badan respons dengan yang baru, atau menghapus badan respons. Beberapa skenario umum untuk memperbarui respons pemirsa setelah mengevaluasi aspek respons dari CloudFront cache atau asal termasuk yang berikut:

Saat Anda bekerja dengan respons HTTP, CloudFront Functions tidak memiliki akses ke badan respons. Anda dapat mengganti konten tubuh dengan mengaturnya ke nilai yang diinginkan, atau Anda dapat menghapus tubuh dengan mengatur nilainya menjadi kosong. Jika Anda tidak memperbarui bidang tubuh dalam fungsi Anda, badan asli yang dikembalikan oleh CloudFront cache atau asal dikembalikan kembali ke penampil.

Jika CloudFront Fungsi Anda dikonfigurasi untuk mengembalikan kesalahan HTTP 400 atau lebih tinggi, penampil Anda tidak akan melihat halaman kesalahan khusus 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.

Nilai string kueri atau objek string kueri

Sebuah fungsi dapat mengembalikan nilai string kueri selain objek string kueri. Nilai string kueri dapat digunakan untuk mengatur parameter string kueri dalam urutan kustom apa pun.

var request = event.request; 
request.querystring = 'ID=42&Exp=1619740800&TTL=1440&NoValue=&querymv=val1&querymv=val2,val3';

Pertimbangan khusus untuk header

Untuk header saja, nama header dikonversi menjadi huruf kecil di objek acara, dan nama header harus huruf kecil ketika ditambahkan oleh kode fungsi Anda. Ketika CloudFront Functions mengubah objek peristiwa 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 mengubahnya menjadi Example-Header-Name permintaan atau respons HTTP.

Host: video.example.com

"headers": {
    "host": {
        "value": "video.example.com"
    }
}

var request = event.request;
var host = request.headers.host.value;

var request = event.request;
request.headers['x-custom-header'] = {value: 'example value'};

Duplikat string kueri, header, dan cookie (array MultiValue)

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.

Accept: application/json
Accept: application/xml
Accept: text/html

"headers": {
    "accept": {
        "value": "application/json",
        "multiValue": [
            {
                "value": "application/json"
            },
            {
                "value": "application/xml"
            },
            {
                "value": "text/html"
            }
        ]
    }
}

Jika kode fungsi Anda memodifikasi string kueri, header, atau cookie yang memiliki multiValue array, CloudFront Functions menggunakan aturan berikut untuk menerapkan perubahan:

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.

Accept: application/json, application/xml, text/html

"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.

Set-Cookie: cookie1=val1; Secure; Path=/; Domain=example.com; 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"
}

Contoh objek respons

Contoh berikut menunjukkan response objek - output dari fungsi respons pemirsa - di mana tubuh telah digantikan oleh fungsi respons pemirsa.

{
  "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-tenant. Untuk distribusi multi-penyewa, endpoint bidang digunakan sebagai pengganti Nilai distributionDomainName endpoint adalah nama CloudFront domain (misalnya, d111111abcdef8.cloudfront.net) dari grup koneksi yang terkait dengan peristiwa.

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