View a markdown version of this page

Permintaan VAST - AWS Elemental MediaTailor
Kapan harus digunakanBidang konfigurasiBagaimana permintaan diprosesBidang responsBagaimana iklan yang diurai berintegrasi dengan output hookPerilaku kegagalanContoh: Mengambil iklan dari server iklan sekunder

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

Permintaan VAST

Kapan harus digunakan

Gunakan VAST_REQUEST saat fungsi Anda perlu mengambil iklan dari titik akhir Template Penayangan Iklan Video (VAST). MediaTailor mengirimkan permintaan, mengurai respons sebagai VAST dengan pengalihan pembungkus diselesaikan, dan membuat iklan yang diurai tersedia untuk ekspresi keluaran Anda. Kasus penggunaan umum termasuk mengambil iklan dari server iklan sekunder untuk melengkapi respons primer singkat, dan mengambil iklan rumah atau promo untuk dimasukkan ke jeda iklan yang kurang terisi.

VAST_REQUESTfungsi didukung di kait PRE_MANIFEST_INSERTION siklus hidup POST_ADS_RESPONSE dan, sendiri atau sebagai langkah di dalam eksekutor. Iklan yang diurai oleh VAST_REQUEST fungsi terintegrasi dengan keluaran kait tersebut dengan kesetiaan penuh. Lihat perinciannya di Bagaimana iklan yang diurai berintegrasi dengan output hook.

Bidang konfigurasi

VAST_REQUESTFungsi memiliki bidang berikut:

  • Runtime — Bahasa ekspresi. Atur ini keJSONATA.

  • MethodType— Metode HTTP. Nilai yang didukung adalah GET (default) danPOST.

  • Ur l — Titik akhir VAST untuk mengirim permintaan. Anda dapat menggunakan URL statis atau ekspresi JSONata yang membangun URL secara dinamis. URL statis harus menggunakan https skema.

  • Header — Header HTTP untuk disertakan dalam permintaan, ditentukan sebagai nama header dan pasangan nilai. Gunakan sintaks {%...%} ekspresi untuk nilai header dinamis.

  • Tubuh — Badan permintaan untuk dikirim. Digunakan dengan POST permintaan, misalnya untuk mengirim permintaan tawaran OpenRTB. Anda dapat menggunakan ekspresi JSONata untuk membangun tubuh secara dinamis.

  • RequestTimeoutMilliseconds(wajib) - Berapa lama menunggu tanggapan.

  • Output — Mendefinisikan nilai yang akan dihasilkan setelah panggilan selesai. Setiap entri memetakan kunci keluaran ke ekspresi yang dapat mereferensikan response objek, termasukresponse.parsedAds.

Batas permintaan HTTP yang berlaku untuk HTTP_REQUEST fungsi juga berlaku di sini. Lihat perinciannya di Batas.

Bagaimana permintaan diproses

  1. Membangun permintaan — MediaTailor mengevaluasiUrl,Headers, dan Body ekspresi terhadap status sesi saat ini, lalu mengirim permintaan. POSTpermintaan dikirim dengan jenis application/json konten.

  2. Parsing respons — MediaTailor mengurai badan respons sebagai VAST. Jika iklan adalah pembungkus VAST, ikuti MediaTailor rantai pengalihan dan selesaikan ke iklan sebaris terakhir. Permintaan pengalihan pembungkus selalu dikirimGET, seperti yang diperlukan spesifikasi VAST. Jika titik akhir Anda mengembalikan dokumen yang berisi URL VAST alih-alih VAST itu sendiri (seperti yang dilakukan beberapa penawar), rangkaian HTTP_REQUEST langkah yang mengambil URL, diikuti dengan VAST_REQUEST langkah yang mengambilnya.

  3. Memproses iklan yang di urai — MediaTailor mengevaluasi ekspresi di blok output. Ekspresi ini dapat mereferensikan status sesi asli dan response objek.

Bidang respons

Setelah panggilan selesai, Anda dapat mereferensikan bidang berikut dalam ekspresi Output Anda:

Bidang Tipe Deskripsi
response.parsedAds Array Iklan yang diurai, dengan pengalihan pembungkus diselesaikan. Setiap iklan memiliki bentuk yang sama dengan adsResponse.ads entri di POST_ADS_RESPONSE kait:adId,durationSeconds,adSystem,adTitle,creativeId,sequence,mediaFiles, dantrackingEvents. Setel ke array kosong ketika panggilan gagal atau responsnya tidak valid VAST.
response.statusCode Bilangan Bulat Kode status HTTP dikembalikan oleh titik akhir. Setel ke null pada kegagalan jaringan.

Karena iklan yang diurai menggunakan bentuk yang sama sepertiadsResponse.ads, Anda dapat memindahkan ekspresi di antara dua permukaan tanpa menulis ulang referensi bidang.

Bagaimana iklan yang diurai berintegrasi dengan output hook

Setiap iklan yang di VAST_REQUEST urai fungsi disimpan secara internal oleh MediaTailor, dikunci oleh ID iklan VAST iklan, selama durasi pemanggilan hook. Ini memberikan perlakuan kelas satu iklan yang diurai dalam output hook:

  • PadaPOST_ADS_RESPONSE, menambahkan iklan yang diurai ke adsResponse.ads by itu adId mengembalikan data VAST lengkap yang diurai iklan, termasuk daftar file media lengkap dan peristiwa pelacakan.

  • DiPRE_MANIFEST_INSERTION, menyuntikkan iklan hanya dengan itu vastAdId memungkinkan MediaTailor memilih file media terbaik dan menangani pendaftaran transcoding secara otomatis.

penting

Iklan yang dipertahankan tidak terbawa di antara pemanggilan kait. Pang VAST_REQUEST gilan yang POST_ADS_RESPONSE dilakukan di tidak tersedia untuk pemang PRE_MANIFEST_INSERTION gilan nanti. Pang VAST_REQUEST gil rantai fungsi hook yang sama tempat Anda menggunakan hasilnya.

Perilaku kegagalan

Jika panggilan gagal karena kesalahan jaringan atau batas waktu, jika titik akhir mengembalikan kesalahan HTTP, atau jika respons tidak dapat diurai sebagai VAST, response.parsedAds adalah array kosong dan rantai fungsi berlanjut. Periksa response.statusCode untuk membedakan kegagalan HTTP dari respons VAST yang benar-benar tidak mengandung iklan.

Tip

Tetap RequestTimeoutMilliseconds kencang. Resolusi pembungkus VAST dapat melibatkan beberapa perjalanan pulang pergi jaringan, dan semuanya diperhitungkan terhadap batas waktu hook dan anggaran hook bersama.

Contoh: Mengambil iklan dari server iklan sekunder

Fungsi berikut mengambil iklan dari server iklan cadangan dan menyimpan iklan yang diurai dalam data sementara. Sel CUSTOM_OUTPUT angkah kemudian dalam urutan yang sama dapat menambahkannya keadsResponse.ads. Ini dirancang untuk kait POST_ADS_RESPONSE siklus hidup.

{
    "FunctionId": "fetchBackupAds",
    "FunctionType": "VAST_REQUEST",
    "VastRequestConfiguration": {
        "Runtime": "JSONATA",
        "MethodType": "GET",
        "Url": "{%'https://backup-ads.example.com/vast?sid=' & session.uuid%}",
        "Headers": {
            "Accept": "application/xml"
        },
        "RequestTimeoutMilliseconds": 1000,
        "Output": {
            "temp.backupAds": "{%response.parsedAds%}"
        }
    }
}

Untuk mengirim permintaan tawaran OpenRTB sebagai gantinya, setel MethodType ke POST dan berikan permintaan tawaran di. Body Penawar harus mengembalikan VAST di badan tanggapan.

Untuk panduan lengkap dari contoh serupa, lihatContoh fungsi.