Metode pembantu untuk modifikasi asal - Amazon CloudFront
Pilih antara CloudFront Fungsi dan Lambda @EdgeupdateRequestOrigin() metodeselectRequestOriginById() metodecreateRequestOriginMetode grup ()

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Metode pembantu untuk modifikasi asal

Bagian ini berlaku jika Anda secara dinamis memperbarui atau mengubah asal yang digunakan pada permintaan di dalam kode CloudFront Fungsi Anda. Anda dapat memperbarui asal hanya pada CloudFront fungsi permintaan penampil. CloudFront Fungsi memiliki modul yang menyediakan metode pembantu untuk memperbarui atau mengubah asal secara dinamis.

Untuk menggunakan modul ini, buat CloudFront fungsi menggunakan JavaScript runtime 2.0 dan sertakan pernyataan berikut di baris pertama kode fungsi:

import cf from 'cloudfront';

Untuk informasi selengkapnya, lihat JavaScript fitur runtime 2.0 untuk Fungsi CloudFront .

catatan

Halaman Test API dan Test console tidak menguji apakah modifikasi asal telah terjadi. Namun, pengujian memastikan bahwa kode fungsi dijalankan tanpa kesalahan.

Pilih antara CloudFront Fungsi dan Lambda @Edge

Anda dapat memperbarui asal Anda dengan menggunakan CloudFront Fungsi atau Lambda @Edge.

Saat menggunakan CloudFront Fungsi untuk memperbarui asal, Anda menggunakan pemicu peristiwa permintaan penampil, yang berarti logika ini akan berjalan pada setiap permintaan saat fungsi ini digunakan. Saat menggunakan Lambda @Edge, kemampuan pembaruan asal ada di pemicu peristiwa permintaan asal, yang berarti logika ini hanya berjalan pada kesalahan cache.

Pilihan Anda sangat bergantung pada beban kerja Anda dan penggunaan CloudFront Fungsi dan Lambda @Edge yang ada pada distribusi Anda. Pertimbangan berikut dapat membantu Anda memutuskan apakah akan menggunakan CloudFront Fungsi atau Lambda @Edge untuk memperbarui asal Anda.

CloudFront Fungsi paling berguna dalam situasi berikut:

  • Ketika permintaan Anda dinamis (artinya mereka tidak dapat di-cache) dan akan selalu pergi ke asal. CloudFront Fungsi memberikan kinerja yang lebih baik dan biaya keseluruhan yang lebih rendah.

  • Ketika Anda sudah memiliki CloudFront fungsi permintaan penampil yang ada yang akan berjalan pada setiap permintaan, Anda dapat menambahkan logika pembaruan asal ke dalam fungsi yang ada.

Untuk menggunakan CloudFront Fungsi untuk memperbarui asal, lihat metode pembantu dalam topik berikut.

Lambda @Edge paling berguna dalam situasi berikut:

  • Ketika Anda memiliki konten yang sangat dapat di-cache, Lambda @Edge bisa lebih hemat biaya karena hanya berjalan pada cache yang gagal, sementara Fungsi berjalan pada setiap permintaan. CloudFront

  • Ketika Anda sudah memiliki fungsi Lambda @Edge permintaan asal yang ada, Anda dapat menambahkan logika pembaruan asal ke fungsi yang ada.

  • Bila logika pembaruan asal Anda memerlukan pengambilan data dari sumber data pihak ketiga, seperti Amazon DynamoDB atau Amazon S3.

Untuk informasi selengkapnya tentang Lambda @Edge, lihat. Sesuaikan di tepi dengan Lambda @Edge

updateRequestOrigin() metode

Gunakan updateRequestOrigin() metode ini untuk memperbarui pengaturan asal untuk permintaan. Anda dapat menggunakan metode ini untuk memperbarui properti asal yang ada untuk asal yang sudah ditentukan dalam distribusi Anda, atau untuk menentukan asal baru untuk permintaan tersebut. Untuk melakukannya, tentukan properti yang ingin Anda ubah.

penting

Pengaturan apa pun yang tidak Anda tentukan updateRequestOrigin() akan mewarisi pengaturan yang sama dari konfigurasi asal yang ada.

Asal yang ditetapkan oleh updateRequestOrigin() metode dapat berupa titik akhir HTTP apa pun dan tidak perlu menjadi asal yang ada dalam CloudFront distribusi Anda.

Catatan

  • Jika Anda memperbarui asal yang merupakan bagian dari grup asal, hanya asal utama grup asal yang diperbarui. Asal sekunder tetap tidak berubah. Kode respons apa pun dari asal yang dimodifikasi yang cocok dengan kriteria failover akan memicu failover ke asal sekunder.

  • Jika Anda mengubah tipe asal dan mengaktifkan OAC, pastikan tipe asal originAccessControlConfig cocok dengan tipe asal baru.

  • Anda tidak dapat menggunakan updateRequestOrigin() metode ini untuk memperbarui asal VPC. Permintaan akan gagal.

Permintaan

updateRequestOrigin({origin properties})

origin propertiesDapat berisi yang berikut:

domainName (opsional)

Nama domain asal. Jika ini tidak disediakan, nama domain dari asal yang ditetapkan digunakan sebagai gantinya.

Untuk asal kustom

Tentukan nama domain DNS, sepertiwww.example.com. Nama domain tidak dapat menyertakan titik dua (:) dan tidak bisa menjadi alamat IP. Nama domain dapat terdiri dari hingga 253 karakter.

Untuk asal S3

Tentukan nama domain DNS bucket Amazon S3, seperti. amzn-s3-demo-bucket.s3.eu-west-1.amazonaws.com Nama bisa sampai 128 karakter dan harus berupa huruf kecil.

originPath (opsional)

Jalur direktori di tempat asal permintaan harus menemukan konten. Jalur harus dimulai dengan garis miring (/) tetapi tidak boleh diakhiri dengan garis miring. Misalnya, seharusnya tidak berakhir denganexample-path/. Jika ini tidak disediakan, maka jalur asal dari asal yang ditetapkan digunakan.

Untuk asal kustom

Jalur harus dikodekan URL dan memiliki panjang maksimum 255 karakter.

CustomHeaders (opsional)

Anda dapat menyertakan judul kustom dengan permintaan dengan menyebutkan nama header dan pasangan nilai untuk masing-masing header khusus. Formatnya berbeda dari header permintaan dan respons dalam struktur acara. Gunakan sintaks pasangan kunci-nilai berikut:

{"key1": "value1", "key2": "value2", ...}

Anda tidak dapat menambahkan header yang tidak diizinkan, dan header dengan nama yang sama juga tidak dapat hadir dalam permintaan masuk. headers Nama header harus huruf kecil dalam kode fungsi Anda. Ketika CloudFront Fungsi mengubah objek acara kembali ke permintaan HTTP, huruf pertama dari setiap kata dalam nama header dikapitalisasi, dan kata-kata dipisahkan oleh tanda hubung.

Misalnya, jika kode fungsi Anda menambahkan header bernamaexample-header-name, CloudFront mengkonversi ini ke Example-Header-Name dalam permintaan HTTP. Untuk informasi selengkapnya, lihat Header khusus yang tidak CloudFront dapat ditambahkan ke permintaan asal dan Pembatasan pada fungsi edge.

Jika ini tidak disediakan, maka header khusus apa pun dari asal yang ditetapkan akan digunakan.

ConnectionAtts (opsional)

Berapa kali yang CloudFront mencoba untuk terhubung ke asal. Minimal adalah 1 dan maksimum adalah 3. Jika ini tidak disediakan, upaya koneksi dari asal yang ditetapkan digunakan.

OriginShield (opsional)

Ini memungkinkan atau memperbarui CloudFront Origin Shield. Menggunakan Shield Asal dapat membantu mengurangi beban pada asal Anda. Untuk informasi selengkapnya, lihat Menggunakan Amazon CloudFront Origin Shield. Jika ini tidak disediakan, pengaturan Origin Shield dari asal yang ditetapkan akan digunakan.

diaktifkan (wajib)

Ekspresi Boolean untuk mengaktifkan atau menonaktifkan Origin Shield. Menerima false nilai true atau.

wilayah (diperlukan saat diaktifkan)

Wilayah AWS Untuk Origin Shield. Tentukan Wilayah AWS yang memiliki latensi terendah pada asal Anda. Gunakan kode Region, bukan nama Region. Misalnya, gunakan us-east-2 untuk menentukan Wilayah Timur AS (Ohio).

Ketika Anda mengaktifkan CloudFront Origin Shield, Anda harus menentukan Wilayah AWS untuk itu. Untuk daftar yang tersedia Wilayah AWS dan membantu memilih Wilayah terbaik untuk asal Anda, lihatMemilih AWS Wilayah untuk Origin Shield.

originAccessControlConfig (opsional)

Pengidentifikasi unik dari kontrol akses asal (OAC) untuk asal ini. Ini hanya digunakan ketika asal mendukung CloudFront OAC, seperti Amazon S3, URLs fungsi MediaStore Lambda, dan V2. MediaPackage Jika ini tidak disediakan, maka pengaturan OAC dari asal yang ditetapkan digunakan.

Ini tidak mendukung identitas akses asal warisan (OAI). Untuk informasi selengkapnya, lihat Batasi akses ke asal AWS.

diaktifkan (wajib)

Ekspresi Boolean untuk mengaktifkan atau menonaktifkan OAC. Menerima false nilai true atau.

SigningBehavior (diperlukan saat diaktifkan)

Menentukan permintaan CloudFront tanda (menambahkan informasi otentikasi ke). Tentukan always untuk kasus penggunaan yang paling umum. Untuk informasi selengkapnya, lihat Pengaturan lanjutan untuk kontrol akses asal.

Bidang ini dapat memiliki salah satu nilai berikut:

  • always— CloudFront menandatangani semua permintaan asal, menimpa Authorization header dari permintaan penampil jika ada.

  • never— CloudFront tidak menandatangani permintaan asal apa pun. Nilai ini mematikan kontrol akses asal untuk asal.

  • no-override— Jika permintaan penampil tidak berisi Authorization header, maka CloudFront tandatangani permintaan asal. Jika permintaan penampil berisi Authorization header, maka CloudFront tidak menandatangani permintaan asal dan sebagai gantinya meneruskan Authorization header dari permintaan penampil.

    Awas

    Untuk meneruskan Authorization header dari permintaan penampil, Anda harus menambahkannya ke kebijakan permintaan asal untuk semua perilaku cache yang menggunakan asal yang terkait dengan kontrol akses asal ini. Untuk informasi selengkapnya, lihat Kontrol permintaan asal dengan kebijakan.

SigningProtocol (diperlukan saat diaktifkan)

Protokol penandatanganan OAC, yang menentukan bagaimana CloudFront tanda (mengotentikasi) permintaan. Satu-satunya nilai yang valid adalah sigv4.

OriginType (diperlukan saat diaktifkan)

Jenis asal untuk OAC ini. Nilai yang valid termasuk s3, mediapackagev2, mediastore, dan lambda.

batas waktu (opsional)

Timeout yang dapat Anda tentukan untuk berapa lama CloudFront harus mencoba menunggu asal merespons atau mengirim data. Jika ini tidak disediakan, maka pengaturan batas waktu dari asal yang ditetapkan digunakan.

ReadTimeout (opsional)

Batas waktu hanya berlaku untuk asal kustom, bukan asal Amazon S3. (Konfigurasi asal S3 akan mengabaikan pengaturan ini.) readTimeoutberlaku untuk kedua nilai berikut:

  • Berapa lama (dalam detik) CloudFront menunggu respons setelah meneruskan permintaan ke asal.

  • Berapa lama (dalam detik) CloudFront menunggu setelah menerima paket respons dari asal dan sebelum menerima paket berikutnya.

Batas waktu minimum adalah 1 detik dan maksimum adalah 60 detik. Untuk informasi selengkapnya, lihat Batas waktu respons (khusus dan hanya asal VPC).

keepAliveTimeout (opsional)

Batas waktu hanya berlaku untuk asal kustom, bukan asal Amazon S3. (Konfigurasi asal S3 akan mengabaikan pengaturan ini.) keepAliveTimeoutmenentukan berapa lama CloudFront harus mencoba untuk mempertahankan koneksi ke asal setelah menerima paket terakhir dari respon. Batas waktu minimum adalah 1 detik dan maksimum adalah 60 detik. Untuk informasi selengkapnya, lihat Keep-alive timeout (khusus dan hanya asal VPC).

ConnectionTimeout (opsional)

Jumlah detik yang CloudFront menunggu ketika mencoba membuat koneksi ke asal. Batas waktu minimum adalah 1 detik dan maksimum 10 detik. Untuk informasi selengkapnya, lihat Batas waktu koneksi.

customOriginConfig (opsional)

Gunakan customOriginConfig untuk menentukan setelan koneksi untuk asal yang bukan bucket Amazon S3. Ada satu pengecualian: Anda dapat menentukan pengaturan ini jika bucket S3 dikonfigurasi dengan hosting situs web statis. (Jenis konfigurasi bucket S3 lainnya akan mengabaikan pengaturan ini.) Jika tidak customOriginConfig disediakan, maka pengaturan dari asal yang ditetapkan digunakan.

port (diperlukan)

Port HTTP yang CloudFront digunakan untuk terhubung ke asal. Tentukan port HTTP yang didengar oleh asal.

protokol (wajib)

Menentukan protokol (HTTP atau HTTPS) yang CloudFront digunakan untuk terhubung ke asal. Nilai yang valid adalah sebagai berikut:

  • http— CloudFront selalu menggunakan HTTP untuk terhubung ke asal

  • https— CloudFront selalu menggunakan HTTPS untuk terhubung ke asal

SSLProtocols (wajib)

Daftar yang menentukan protokol SSL/TLS minimum yang CloudFront digunakan saat menghubungkan ke asal Anda melalui HTTPS. Nilai yang valid termasuk SSLv3, TLSv1, TLSv1.1, dan TLSv1.2. Untuk informasi selengkapnya, lihat Protokol SSL asal minimum.

contoh - Perbarui ke asal permintaan Amazon S3

Contoh berikut mengubah asal permintaan viewer ke bucket S3, mengaktifkan OAC, dan mengatur ulang header kustom yang dikirim ke asal.

cf.updateRequestOrigin({
    "domainName" : "amzn-s3-demo-bucket-in-us-east-1.s3.us-east-1.amazonaws.com",
    "originAccessControlConfig": {
        "enabled": true,
        "signingBehavior": "always",
        "signingProtocol": "sigv4",
        "originType": "s3"
    },
    // Empty object resets any header configured on the assigned origin
    "customHeaders": {}
});
contoh — Perbarui ke asal permintaan Application Load Balancer

Contoh berikut mengubah asal permintaan viewer ke asal Application Load Balancer dan menetapkan header dan batas waktu kustom.

cf.updateRequestOrigin({
    "domainName" : "example-1234567890.us-east-1.elb.amazonaws.com",
    "timeouts": {
        "readTimeout": 30,
        "connectionTimeout": 5
    },
    "customHeaders": {
        "x-stage": "production",
        "x-region": "us-east-1"
    }
});
contoh — Perbarui ke asal dengan Origin Shield diaktifkan

Dalam contoh berikut, asal dalam distribusi mengaktifkan Origin Shield. Kode fungsi hanya memperbarui nama domain yang digunakan untuk asal dan menghilangkan semua parameter opsional lainnya. Dalam hal ini, Origin Shield akan tetap digunakan dengan nama domain asal yang dimodifikasi karena parameter Origin Shield tidak diperbarui.

cf.updateRequestOrigin({
    "domainName" : "www.example.com"
});

selectRequestOriginById() metode

Gunakan selectRequestOriginById() untuk memperbarui asal yang ada dengan memilih asal berbeda yang sudah dikonfigurasi dalam distribusi Anda. Metode ini menggunakan semua pengaturan yang sama yang ditentukan oleh asal yang diperbarui.

Metode ini hanya menerima asal yang sudah ditentukan dalam distribusi yang sama yang digunakan saat menjalankan fungsi. Origins direferensikan oleh ID asal, yang merupakan nama asal yang Anda tentukan saat mengatur asal.

Jika Anda memiliki asal VPC yang dikonfigurasi dalam distribusi Anda, Anda dapat menggunakan metode ini untuk memperbarui asal Anda ke asal VPC Anda. Untuk informasi selengkapnya, lihat Batasi akses dengan asal VPC.

Permintaan

selectRequestOriginById(origin_id)

Dalam contoh sebelumnya, origin_id adalah string yang menunjuk ke nama asal asal dalam distribusi yang menjalankan fungsi.

contoh — Pilih asal permintaan Amazon S3

Contoh berikut memilih asal yang dinamai amzn-s3-demo-bucket-in-us-east-1 dari daftar asal yang terkait dengan distribusi, dan menerapkan pengaturan konfigurasi amzn-s3-demo-bucket-in-us-east-1 asal ke permintaan.

cf.selectRequestOriginById("amzn-s3-demo-bucket-in-us-east-1");
contoh — Pilih asal permintaan Application Load Balancer

Contoh berikut memilih asal Application Load Balancer myALB-prod bernama dari daftar asal yang terkait dengan distribusi, dan menerapkan pengaturan konfigurasi untuk myALB-prod permintaan.

cf.selectRequestOriginById("myALB-prod");

createRequestOriginMetode grup ()

Gunakan createRequestOriginGroup() untuk mendefinisikan dua asal untuk digunakan sebagai grup asal untuk failover dalam skenario yang membutuhkan ketersediaan tinggi.

Grup asal mencakup dua asal (primer dan sekunder) dan kriteria failover yang Anda tentukan. Anda membuat grup asal untuk mendukung failover asal. CloudFront Saat membuat atau memperbarui grup asal menggunakan metode ini, Anda dapat menentukan grup asal, bukan satu asal. CloudFront akan failover dari asal primer ke asal sekunder, menggunakan kriteria failover.

Jika Anda memiliki asal VPC yang dikonfigurasi dalam distribusi Anda, Anda dapat menggunakan metode ini untuk membuat grup asal menggunakan asal VPC. Untuk informasi selengkapnya, lihat Batasi akses dengan asal VPC.

Permintaan

createRequestOriginGroup({origin_group_properties})

Dalam contoh sebelumnya, origin_group_properties dapat berisi yang berikut:

OriginIds (wajib)

Array dariorigin_ids, di mana origin_id adalah string yang menunjuk ke nama asal asal dalam distribusi yang menjalankan fungsi. Anda harus memberikan dua asal sebagai bagian dari array. Asal pertama dalam daftar adalah asal primer dan yang kedua berfungsi sebagai asal kedua untuk tujuan failover.

SelectionCriteria (opsional)

Pilih apakah akan menggunakan kriteria failover default asal atau menggunakan logika failover media-quality-score berbasis. Nilai yang valid adalah sebagai berikut:

  • defaultmenggunakan kriteria failover, berdasarkan kode status yang ditentukan dalam. failoverCriteria Jika Anda tidak mengatur selectionCriteria fungsi, default akan digunakan.

  • media-quality-scoredigunakan ketika kemampuan perutean sadar media sedang digunakan.

FailOverCriteria (wajib)

Array kode status yang, ketika dikembalikan dari asal primer, akan memicu failover CloudFront ke asal sekunder. Jika Anda menimpa grup asal yang ada, larik ini akan menimpa semua kode status failover yang ditetapkan dalam konfigurasi asli grup asal.

Saat Anda menggunakan media-quality-scoreselectionCriteria, CloudFront akan mencoba untuk merutekan permintaan berdasarkan skor kualitas media. Jika asal yang dipilih mengembalikan kode kesalahan yang diatur dalam array ini, CloudFront akan failover ke asal lainnya.

contoh — Buat grup asal permintaan

Contoh berikut membuat grup asal untuk permintaan menggunakan asal IDs. Asal ini IDs berasal dari konfigurasi grup asal untuk distribusi yang digunakan untuk menjalankan fungsi ini.

cf.createRequestOriginGroup({
    originIds: ["us-east-1-s3-origin", "us-west-2-s3-origin"],
    failoverCriteria: {
        statusCodes: [500, 502, 503, 504] 
    }
});