Mengelola jalur pengiriman

  • Artikel

Gunakan metode ini di API promosi Microsoft Store untuk membuat satu atau beberapa jalur pengiriman untuk membeli inventori dan menayangkan iklan Anda untuk kampanye iklan promosi. Untuk setiap jalur pengiriman, Anda dapat menetapkan penargetan, menetapkan harga penawaran Anda, dan memutuskan berapa banyak yang ingin Anda belanjakan dengan menetapkan anggaran dan menautkan ke materi iklan yang ingin Anda gunakan.

Untuk informasi selengkapnya tentang hubungan antara baris pengiriman dan kampanye iklan, profil penargetan, dan materi iklan, lihat Menjalankan kampanye iklan menggunakan layanan Microsoft Store.

Catatan Sebelum berhasil membuat jalur pengiriman untuk kampanye iklan menggunakan API ini, Anda harus terlebih dahulu membuat satu kampanye iklan berbayar menggunakan halaman Kampanye iklan di Pusat Mitra, dan Anda harus menambahkan setidaknya satu instrumen pembayaran di halaman ini. Setelah melakukan ini, Anda akan berhasil membuat jalur pengiriman yang dapat ditagih untuk kampanye iklan menggunakan API ini. Kampanye iklan yang Anda buat menggunakan API akan secara otomatis menagih instrumen pembayaran default yang dipilih di halaman Kampanye iklan di Pusat Mitra.

Prasyarat

Untuk menggunakan metode ini, Anda harus terlebih dahulu melakukan hal berikut:

  • Jika Anda belum melakukannya, selesaikan semua prasyarat untuk API promosi Microsoft Store.

    Catatan

    Sebagai bagian dari prasyarat, pastikan Anda membuat setidaknya satu kampanye iklan berbayar di Pusat Mitra dan Anda menambahkan setidaknya satu instrumen pembayaran untuk kampanye iklan di Pusat Mitra. Baris pengiriman yang Anda buat menggunakan API ini akan secara otomatis menagih instrumen pembayaran default yang dipilih di halaman Kampanye iklan di Pusat Mitra.

  • Dapatkan token akses Azure AD untuk digunakan di header permintaan untuk metode ini. Setelah mendapatkan token akses, Anda memiliki waktu 60 menit untuk menggunakannya sebelum masa berlakunya habis. Setelah token kedaluwarsa, Anda dapat memperoleh yang baru.

Minta

Metode ini memiliki URI berikut.

Jenis metode Meminta URI Deskripsi
POSTING https://manage.devcenter.microsoft.com/v1.0/my/promotion/line Membuat jalur pengiriman baru.
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Mengedit baris pengiriman yang ditentukan oleh lineId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/{lineId} Mendapatkan jalur pengiriman yang ditentukan oleh lineId.
Header Jenis Deskripsi
Authorization string Wajib diisi. Token akses Azure AD dalam bentuktoken>Pembawa<.
ID Pelacakan GUID Pilihan. ID yang melacak alur panggilan.

Isi permintaan

Metode POST dan PUT memerlukan isi permintaan JSON dengan bidang objek baris Pengiriman yang diperlukan dan bidang tambahan apa pun yang ingin Anda atur atau ubah.

Contoh permintaan

Contoh berikut menunjukkan cara memanggil metode POST untuk membuat jalur pengiriman.

POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/line HTTP/1.1
Authorization: Bearer <your access token>

{
    "name": "Contoso App Campaign - Paid Line",
    "configuredStatus": "Active",
    "startDateTime": "2017-01-19T12:09:34Z",
    "endDateTime": "2017-01-31T23:59:59Z",
    "bidAmount": 0.4,
    "dailyBudget": 20,
    "targetProfileId": {
        "id": 310021746
    },
    "creatives": [
        {
            "id": 106851
        }
    ],
    "campaignId": 31043481,
    "minMinutesPerImp ": 1
}

Contoh berikut menunjukkan cara memanggil metode GET untuk mengambil jalur pengiriman.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/line/31019990  HTTP/1.1
Authorization: Bearer <your access token>

Respons

Metode ini mengembalikan isi respons JSON dengan objek Baris pengiriman yang berisi informasi tentang baris pengiriman yang dibuat, diperbarui, atau diambil. Contoh berikut menunjukkan isi respons untuk metode ini.

{
    "Data": {
        "id": 31043476,
        "name": "Contoso App Campaign - Paid Line",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "startDateTime": "2017-01-19T12:09:34Z",
        "endDateTime": "2017-01-31T23:59:59Z",
        "createdDateTime": "2017-01-17T10:28:34Z",
        "bidType": "CPM",
        "bidAmount": 0.4,
        "dailyBudget": 20,
        "targetProfileId": {
            "id": 310021746
        },
        "creatives": [
            {
                "id": 106126
            }
        ],
        "campaignId": 31043481,
        "minMinutesPerImp ": 1,
        "pacingType ": "SpendEvenly",
        "currencyId ": 732
    }
}

Objek baris pengiriman

Badan permintaan dan respons untuk metode ini berisi bidang berikut. Tabel ini memperlihatkan bidang mana yang bersifat baca-saja (artinya tidak dapat diubah dalam metode PUT) dan bidang mana yang diperlukan dalam isi permintaan untuk metode POST atau PUT.

Bidang Jenis Deskripsi Baca saja Default Diperlukan untuk POST/PUT
id bilangan bulat ID jalur pengiriman. Ya Tidak
nama string Nama jalur pengiriman. Tidak POST
configuredStatus string Salah satu nilai berikut yang menentukan status baris pengiriman yang ditentukan oleh pengembang:
  • Aktif
  • Tidak aktif
 Tidak POST
effectiveStatus string Salah satu nilai berikut yang menentukan status efektif jalur pengiriman berdasarkan validasi sistem:
  • Aktif
  • Tidak aktif
  • Processing
  • Gagal
 Ya Tidak
effectiveStatusReasons array Satu atau beberapa nilai berikut yang menentukan alasan status efektif baris pengiriman:
  • AdCreativesInactive
  • ValidationFailed
 Ya Tidak
startDatetime string Tanggal dan waktu mulai untuk baris pengiriman, dalam format ISO 8601. Nilai ini tidak dapat diubah jika sudah ada di masa lalu. Tidak POST, PUT
endDatetime string Tanggal dan waktu akhir untuk baris pengiriman, dalam format ISO 8601. Nilai ini tidak dapat diubah jika sudah ada di masa lalu. Tidak POST, PUT
createdDatetime string Tanggal dan waktu baris pengiriman dibuat, dalam format ISO 8601. Ya Tidak
bidType string Nilai yang menentukan jenis penawaran dari baris pengiriman. Saat ini, satu-satunya nilai yang didukung adalah CPM. Tidak BPT Tidak
bidAmount decimal Jumlah penawaran yang akan digunakan untuk mengajukan penawaran permintaan iklan apa pun. Tidak Nilai CPM rata-rata berdasarkan target pasar (nilai ini direvisi secara berkala). Tidak
dailyBudget decimal Anggaran harian untuk jalur pengiriman. DailyBudget atau lifetimeBudget harus diatur. Tidak POST, PUT (jika lifetimeBudget tidak diatur)
lifetimeBudget decimal Anggaran seumur hidup untuk jalur pengiriman. LifetimeBudget* atau dailyBudget harus diatur. Tidak POST, PUT (jika dailyBudget tidak diatur)
targetingProfileId objek Pada objek yang mengidentifikasi profil penargetan yang menjelaskan pengguna, geografi, dan jenis inventori yang ingin Anda targetkan untuk jalur pengiriman ini. Objek ini terdiri dari bidang id tunggal yang menentukan ID profil penargetan. Tidak Tidak
Kreasi array Satu atau beberapa objek yang mewakili materi iklan yang terkait dengan jalur pengiriman. Setiap objek dalam bidang ini terdiri dari bidang id tunggal yang menentukan ID materi iklan. Tidak Tidak
campaignId bilangan bulat ID kampanye iklan induk. Tidak Tidak
minMinutesPerImp bilangan bulat Menentukan interval waktu minimum (dalam menit) antara dua tayangan yang ditampilkan kepada pengguna yang sama dari baris pengiriman ini. Tidak 4000 Tidak
pacingType string Salah satu nilai berikut yang menentukan jenis pacing:
  • SpendEvenly
  • SpendAsFastAsPossible
 Tidak SpendEvenly Tidak
currencyId bilangan bulat ID mata uang kampanye. Ya Mata uang akun pengembang (Anda tidak perlu menentukan bidang ini dalam panggilan POST atau PUT) Tidak