Members

Nota: a partire dal 31 marzo 2020, l'endpoint members sostituisce l'endpoint sponsors, che è deprecato e non sarà più supportato a partire dal 30 settembre 2020. I client API devono aggiornare le chiamate al metodo sponsors.list per utilizzare invece il metodo members.list.

Questo endpoint può essere utilizzato solo da singoli creator per effettuare richieste relative al proprio canale YouTube abilitato per gli abbonamenti. Rivolgiti al tuo rappresentante di Google o YouTube per richiedere l'accesso.

Una risorsa member rappresenta un membro del canale per un canale YouTube. Un abbonato fornisce un supporto monetario ricorrente a un creator e riceve vantaggi speciali. Ad esempio, gli abbonati possono chattare quando il creator attiva la modalità riservata agli abbonati per una chat.

Metodi

L'API supporta i seguenti metodi per le risorse di member:

list
Elenca i membri (in precedenza chiamati "sponsor") di un canale. La richiesta API deve essere autorizzata dal proprietario del canale.

Rappresentazione delle risorse

La seguente struttura JSON mostra il formato di una risorsa 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,
        }
      ]
    }
  }
}

Proprietà

La tabella seguente definisce le proprietà che vengono visualizzate in questa risorsa:

Proprietà
kind string
Identifica il tipo di risorsa API. Il valore sarà youtube#member.
etag etag
L'Etag di questa risorsa.
snippet object
L'oggetto snippet contiene i dettagli relativi al membro.
snippet.creatorChannelId string
L'ID canale YouTube del creator che offre gli abbonamenti.
snippet.memberDetails object
Questo oggetto contiene dati di profilo relativi al canale YouTube che paga l'abbonamento.

Tieni presente che un canale può avere abbonati con dati di profilo non disponibili. Questo accade ad esempio agli abbonati che hanno eliminato i loro canali, ma pagano ancora per gli abbonamenti. Tieni presente che questi abbonati possono comunque usufruire dei vantaggi dell'abbonamento.

Le risposte dell'API includono risorse per i membri al fine di garantire conteggi precisi, anche se i dettagli del profilo all'interno dell'oggetto memberDetails non sono impostati. Gli membershipsDetails vengono comunque forniti per questi membri.
snippet.memberDetails.channelId string
L'ID del canale YouTube dell'abbonato. Se impostato, l'ID canale può anche essere considerato come un identificatore univoco dell'abbonato. Se non è impostato, il membro non può essere identificato in modo univoco, ma la risorsa trasmette comunque i dettagli dell'abbonamento, ad esempio i livelli a cui può accedere e la durata dell'abbonamento.
snippet.memberDetails.channelUrl string
L'URL del canale.
snippet.memberDetails.displayName string
Il nome visualizzato del canale.
snippet.memberDetails.profileImageUrl string
L'URL dell'avatar del canale.
snippet.membershipsDetails object
Questo oggetto contiene i dettagli dell'abbonamento al canale membro.
snippet.membershipsDetails.highestAccessibleLevel string
L'ID del livello dell'abbonamento più alto a cui il canale abbonato può attualmente accedere. Il valore corrisponde al valore della proprietà id in una risorsa membershipsLevel.
snippet.membershipsDetails.highestAccessibleLevelDisplayName string
Il nome del livello dell'abbonamento con il livello più alto di accesso a cui il canale abbonato può attualmente accedere. Il valore corrisponde al valore della proprietà displayName in una risorsa membershipsLevel.
snippet.membershipsDetails.accessibleLevels[] list (of strings)
Un elenco di ID per tutti i livelli di abbonamento a cui l'utente può attualmente accedere. L'elenco include il livello attualmente attivo e tutti i livelli sottostanti.
snippet.membershipsDuration object
Questo oggetto contiene informazioni sulla durata complessiva dell'abbonamento attuale dell'utente indipendentemente dai livelli dei prezzi. La proprietà snippet.membershipsDetails.membershipsDurationAtLevel[] contiene quindi un elenco di oggetti che contengono i dettagli relativi a un periodo di appartenenza durante il quale il membro ha avuto accesso a un determinato livello di appartenenza.

L'esempio seguente mostra come funzionano queste proprietà: un abbonato acquista un nuovo abbonamento a gennaio al livello 1 e ha quell'abbonamento fino a marzo. Ad aprile e maggio, l'abbonato non ha un abbonamento. A giugno, l'abbonamento sarà di nuovo al livello 1. Successivamente, nel mese di agosto, eseguirà l'upgrade all'abbonamento di livello 2. Quindi, se una chiamata API viene effettuata a ottobre, la risorsa member conterrà quanto segue: 
"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
La data e l'ora di inizio dell'attuale abbonamento dell'abbonato. In altre parole, l'abbonamento è sempre stato sottoscritto da questa data e ora. Tieni presente che periodi di abbonamento diversi potrebbero essere stati applicati a livelli di abbonamento diversi.
snippet.membershipsDuration.memberTotalDurationMonths integer
Il numero di mesi, arrotondato per difetto al numero intero più vicino, di cui l'utente è stato membro. Il valore rispecchia il numero di mesi interi per i quali l'abbonato ha usufruito dell'abbonamento, ma non significa che l'utente abbia usufruito di un'iscrizione per quel numero di mesi.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[] list (of objects)
Un elenco di oggetti, in cui ogni oggetto contiene dettagli su un periodo dell'appartenenza durante il quale l'utente ha avuto l'accesso a un determinato livello di appartenenza. L'elenco include un oggetto per ogni livello di appartenenza al quale il membro può attualmente accedere.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.level string
L'ID del livello dell'abbonamento. Il valore corrisponde al valore della proprietà id in una risorsa membershipsLevel.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberSince datetime
La data e l'ora in cui l'abbonato ha avuto accesso al livello dell'abbonamento specificato. In altre parole, l'abbonato ha avuto accesso costante al livello da questa data e ora. Tieni presente che periodi di abbonamento diversi potrebbero essere stati spesi a livelli più elevati.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
Il numero di mesi, arrotondato per difetto al numero intero più vicino, a cui l'utente ha avuto accesso al livello specificato. Il valore riflette il numero di mesi completi per i quali l'abbonato ha avuto accesso al livello, ma il numero non implica la sottoscrizione di un abbonamento per quei mesi.