Members

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

Questo endpoint può essere utilizzato solo dai singoli creator per effettuare richieste per il proprio canale YouTube su cui sono abilitati gli abbonamenti. Per richiedere l'accesso, contatta il tuo rappresentante di Google o YouTube.

Una risorsa member rappresenta un abbonato a un canale YouTube. Un abbonato fornisce un sostegno finanziario 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 member:

list
Elenca gli abbonati (in precedenza noti come "sponsor") di un canale. La richiesta all'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à 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 del membro.
snippet.creatorChannelId string
L'ID canale YouTube del creator che offre gli abbonamenti.
snippet.memberDetails object
Questo oggetto contiene i dati di profilo del canale YouTube che paga l'abbonamento.

Tieni presente che un canale può avere abbonati con dati del profilo non disponibili. Ad esempio, accade agli abbonati che hanno eliminato i propri canali, ma continuano a pagare gli abbonamenti. Tieni presente che questi abbonati possono comunque accedere ai vantaggi dell'abbonamento.

Le risposte dell'API includono risorse per questi membri per garantire conteggi accurati anche se i dettagli del profilo all'interno dell'oggetto memberDetails non sono impostati. I membershipsDetails continueranno a essere disponibili per questi abbonati.
snippet.memberDetails.channelId string
L'ID canale YouTube del canale dell'abbonato. Se è impostato, l'ID canale può essere considerato anche come identificatore univoco per l'abbonato. Se non è impostato, l'abbonamento non può essere identificato in modo univoco, ma la risorsa trasmette comunque i dettagli dell'abbonamento, ad esempio i livelli a cui l'abbonato 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 del membro.
snippet.membershipsDetails.highestAccessibleLevel string
L'ID del livello di abbonamento più alto a cui il canale membro può accedere al momento. Il valore corrisponde al valore della proprietà id in una risorsa membershipsLevel.
snippet.membershipsDetails.highestAccessibleLevelDisplayName string
Il nome del livello di abbonamento più alto a cui il canale membro può accedere al momento. 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ò accedere al momento. L'elenco include il livello attualmente attivo e tutti i livelli sottostanti.
snippet.membershipsDuration object
Questo oggetto contiene informazioni sulla durata complessiva dell'abbonamento dell'abbonato corrente, indipendentemente dai livelli di prezzo. La proprietà snippet.membershipsDetails.membershipsDurationAtLevel[] contiene un elenco di oggetti che contengono dettagli su un periodo dell'abbonamento durante il quale l'abbonato aveva accesso a un determinato livello di abbonamento.

Il seguente esempio mostra il funzionamento di queste proprietà: un abbonato acquista un nuovo abbonamento a gennaio al livello 1 e lo utilizza fino a marzo. Ad aprile e maggio, il cliente non ha un abbonamento. A giugno, l'abbonato riavvia il proprio abbonamento, nuovamente al livello 1. A agosto, l'abbonato esegue l'upgrade dell'abbonamento al livello 2. Pertanto, se viene effettuata una chiamata API 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'abbonamento attuale dell'abbonato. In altre parole, il membro ha un abbonamento da questa data e ora. Tieni presente che periodi diversi dell'abbonamento potrebbero essere stati trascorsi a livelli di abbonamento diversi.
snippet.membershipsDuration.memberTotalDurationMonths integer
Il numero di mesi, arrotondato per difetto al numero intero più vicino, durante i quali l'utente è stato membro. Il valore riflette il numero di mesi completi per i quali l'abbonato ha sottoscritto un abbonamento, ma il numero non implica che l'abbonato abbia avuto un abbonamento ininterrotto per tutti questi mesi.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[] list (of objects)
Un elenco di oggetti, in cui ogni oggetto contiene i dettagli di un periodo dell'abbonamento durante il quale l'abbonato aveva accesso a un determinato livello di abbonamento. L'elenco include un oggetto per ogni livello di abbonamento a cui l'abbonato può accedere al momento.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.level string
L'ID 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 a partire dalle quali l'abbonato ha avuto accesso al livello di abbonamento specificato. In altre parole, il membro ha avuto accesso continuo al livello da questa data e ora. Tieni presente che periodi diversi dell'abbonamento potrebbero essere stati trascorsi a livelli di abbonamento superiori.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
Il numero di mesi, arrotondato per difetto al numero intero più vicino, durante i quali l'utente ha avuto accesso al livello specificato. Il valore riflette il numero di mesi completi per i quali il membro ha avuto accesso al livello, ma il numero non implica che il membro abbia avuto un abbonamento per tutti questi mesi.