Members

Catatan: Mulai 31 Maret 2020, endpoint members menggantikan endpoint sponsors, yang kini tidak digunakan lagi dan tidak akan didukung lagi pada atau setelah 30 September 2020. Klien API harus memperbarui panggilan ke metode sponsors.list agar menggunakan metode members.list.

Endpoint ini hanya dapat digunakan oleh masing-masing kreator untuk membuat permintaan untuk channel YouTube mereka sendiri yang mengaktifkan langganan channel. Hubungi perwakilan Google atau YouTube Anda untuk meminta akses.

Referensi member merepresentasikan pelanggan channel untuk sebuah channel YouTube. Pelanggan memberikan dukungan moneter berulang kepada kreator dan menerima manfaat khusus. Misalnya, pelanggan dapat melakukan chat saat kreator mengaktifkan mode khusus pelanggan untuk chat.

Metode

API ini mendukung metode berikut untuk resource member:

list
Mencantumkan anggota (sebelumnya dikenal sebagai "sponsor") untuk sebuah channel. Permintaan API harus diotorisasi oleh pemilik saluran.

Representasi resource

Struktur JSON berikut menampilkan format resource member:

{
  "kind": "youtube#member",
  "etag": etag,
  "snippet": {
    "creatorChannelId": string,
    "memberDetails": {
      "channelId": string,
      "channelUrl": string,
      "displayName": string,
      "profileImageUrl": string
    },
    "membershipsDetails": {
      "highestAccessibleLevel": string,
      "highestAccessibleLevelDisplayName": string,
      "accessibleLevels": [
        string
      ],
      "membershipsDuration": {
        "memberSince": datetime,
        "memberTotalDurationMonths": integer,
      },
      "membershipsDurationAtLevel": [
        {
          "level": string,
          "memberSince": datetime,
          "memberTotalDurationMonths": integer,
        }
      ]
    }
  }
}

Properti

Tabel berikut mendefinisikan properti yang muncul di resource ini:

Properti
kind string
Mengidentifikasi jenis resource API. Nilainya akan berupa youtube#member.
etag etag
Etag resource ini.
snippet object
Objek snippet berisi detail tentang anggota.
snippet.creatorChannelId string
ID channel YouTube kreator yang menawarkan langganan.
snippet.memberDetails object
Objek ini berisi data profil tentang channel YouTube yang membayar langganan.

Perhatikan bahwa channel dapat memiliki pelanggan yang data profilnya tidak tersedia. Misalnya, hal ini terjadi pada pelanggan yang telah menghapus channel-nya, tetapi masih membayar langganan. Perlu diperhatikan bahwa anggota ini masih dapat mengakses manfaat langganannya.

Respons API menyertakan resource untuk anggota tersebut guna memastikan penghitungan yang akurat meskipun detail profil di dalam objek memberDetails tidak ditetapkan. membershipsDetails akan tetap disediakan untuk pelanggan tersebut.
snippet.memberDetails.channelId string
ID channel YouTube dari channel pelanggan. Jika disetel, ID channel juga dapat diperlakukan sebagai ID unik untuk pelanggan. Jika tidak ditetapkan, anggota tidak dapat diidentifikasi secara unik, tetapi resource tetap menyampaikan detail keanggotaan seperti level yang dapat diakses anggota dan durasi keanggotaannya.
snippet.memberDetails.channelUrl string
URL channel.
snippet.memberDetails.displayName string
Nama tampilan channel.
snippet.memberDetails.profileImageUrl string
URL avatar channel.
snippet.membershipsDetails object
Objek ini berisi detail langganan untuk channel pelanggan.
snippet.membershipsDetails.highestAccessibleLevel string
ID level langganan tertinggi yang saat ini dapat diakses oleh channel pelanggan. Nilai ini sesuai dengan nilai properti id di resource membershipsLevel.
snippet.membershipsDetails.highestAccessibleLevelDisplayName string
Nama level langganan tertinggi yang saat ini dapat diakses oleh channel pelanggan. Nilai ini sesuai dengan nilai properti displayName di resource membershipsLevel.
snippet.membershipsDetails.accessibleLevels[] list (of strings)
Daftar ID untuk semua level langganan yang saat ini dapat diakses oleh pengguna. Daftar ini mencakup level yang saat ini aktif dan semua level di bawahnya.
snippet.membershipsDuration object
Objek ini berisi informasi tentang durasi keseluruhan langganan anggota saat ini tanpa bergantung pada tingkat harga. Properti snippet.membershipsDetails.membershipsDurationAtLevel[] kemudian berisi daftar objek yang berisi detail tentang periode keanggotaan saat anggota memiliki akses ke level keanggotaan tertentu.

Contoh berikut menunjukkan cara kerja properti ini: Pelanggan membeli langganan baru pada bulan Januari di level langganan 1 dan memiliki langganan tersebut hingga bulan Maret. Pada bulan April dan Mei, anggota tidak memiliki langganan. Pada bulan Juni, pelanggan tersebut memulai ulang langganannya, lagi di level 1. Kemudian, pada bulan Agustus, pelanggan mengupgrade langganannya ke level 2. Jadi, jika panggilan API dilakukan pada bulan Oktober, resource member akan berisi hal berikut: 
"membershipsDetails": {
  "membershipsDuration": {
    "memberSince": "2020-06-01T12:00:00",
    "memberTotalDurationMonths": 7,
  },
  "membershipsDurationAtLevel": [
    {
      "level": "level_1_ID",
      "memberSince": "2020-06-01T12:00:00",
      "memberTotalDurationMonths": 7
    },
    {
      "level": "level_2_ID",
      "memberSince": "2020-08-01T12:00:00",
      "memberTotalDurationMonths": 2
    },
  ]
}
snippet.membershipsDuration.memberSince datetime
Tanggal dan waktu langganan pelanggan saat ini dimulai. Dengan kata lain, anggota telah terus memiliki langganan sejak tanggal dan waktu tersebut. Perhatikan bahwa periode langganan yang berbeda mungkin dihabiskan pada level langganan yang berbeda.
snippet.membershipsDuration.memberTotalDurationMonths integer
Jumlah bulan, yang dibulatkan ke bawah ke bilangan bulat terdekat, saat pengguna telah menjadi pelanggan. Nilai ini mencerminkan jumlah bulan penuh saat anggota memiliki langganan, tetapi angka ini tidak berarti bahwa pelanggan telah terus memiliki langganan selama bulan tersebut.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[] list (of objects)
Daftar objek, yang setiap objeknya berisi detail tentang periode keanggotaan saat anggota memiliki akses ke level keanggotaan tertentu. Daftar ini menyertakan satu objek untuk setiap level keanggotaan yang saat ini dapat diakses oleh anggota.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.level string
ID level langganan. Nilai ini sesuai dengan nilai properti id di resource membershipsLevel.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberSince datetime
Tanggal dan waktu saat pelanggan dapat mengakses level langganan yang ditentukan. Dengan kata lain, anggota terus memiliki akses ke level sejak tanggal dan waktu tersebut. Perhatikan bahwa periode langganan yang berbeda mungkin telah dibelanjakan pada level langganan yang lebih tinggi.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
Jumlah bulan, yang dibulatkan ke bawah ke bilangan bulat terdekat, saat pengguna memiliki akses ke tingkat yang ditentukan. Nilai ini mencerminkan jumlah bulan penuh saat pelanggan dapat mengakses level, tetapi angka ini tidak berarti bahwa pelanggan telah terus berlangganan selama bulan tersebut.