Members

Nota: a partire dal 31 marzo 2020, l'endpoint members sostituisce l'endpoint sponsors, che è ora 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 il metodo members.list.

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

Una risorsa member rappresenta l'abbonamento a un canale YouTube. Un abbonato fornisce un sostegno economico 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 i membri di un canale (precedentemente noti come "sponsor"). 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à 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 sul membro.
snippet.creatorChannelId string
L'ID canale YouTube del creator che offre gli abbonamenti.
snippet.memberDetails object
Questo oggetto contiene i dati del profilo relativi al canale YouTube che paga l'abbonamento.

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

Le risposte dell'API includono risorse per i membri in modo da garantire conteggi accurati anche se i dettagli del profilo all'interno dell'oggetto memberDetails non sono impostati. I membershipsDetails sono comunque forniti per questi membri.
snippet.memberDetails.channelId string
L'ID del canale YouTube del canale abbonato. Se impostato, l'ID canale può anche essere trattato come un identificatore univoco dell'abbonato. Se non viene configurato, il membro non può essere identificato in modo univoco, ma la risorsa trasmette comunque i dettagli dell'appartenenza, come i livelli a cui il membro 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 per il canale per gli abbonati.
snippet.membershipsDetails.highestAccessibleLevel string
L'ID del livello dell'abbonamento più elevato a cui può accedere attualmente il canale dell'abbonamento. Il valore corrisponde al valore della proprietà id in una risorsa membershipsLevel.
snippet.membershipsDetails.highestAccessibleLevelDisplayName string
Il nome del livello dell'abbonamento più elevato a cui può accedere attualmente il canale dell'abbonamento. 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 dell'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 a prescindere dai livelli di prezzo. La proprietà snippet.membershipsDetails.membershipsDurationAtLevel[] contiene quindi un elenco di oggetti con dettagli su un periodo dell'abbonamento durante il quale il membro ha avuto accesso a un determinato livello dell'abbonamento.

L'esempio seguente mostra come funzionano queste proprietà: un membro acquista un nuovo abbonamento a gennaio al livello 1 dell'abbonamento e mantiene l'abbonamento fino a marzo. Ad aprile e maggio, i membri non sono abbonati. A giugno, l'abbonamento ripristina il livello 1. Poi, ad agosto, l'abbonato può eseguire l'upgrade del proprio abbonamento al livello 2. Quindi, 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 continuato ad avere un abbonamento da questa data e ora. Tieni presente che periodi diversi dell'abbonamento potrebbero essere stati spesi per diversi livelli dell'abbonamento.
snippet.membershipsDuration.memberTotalDurationMonths integer
Il numero di mesi, arrotondati per difetto al numero intero più vicino, durante i quali l'utente è stato membro. Il valore riflette il numero di mesi completi dell'abbonamento, ma il numero non implica che l'abbonamento sia stato attivo ininterrottamente per tanti mesi.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[] list (of objects)
Un elenco di oggetti, in cui ciascun oggetto contiene dettagli su un periodo di appartenenza durante il quale il membro ha avuto accesso a un determinato livello di appartenenza. L'elenco include un oggetto per ogni livello dell'abbonamento a cui 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 a partire dalle quali l'abbonato ha avuto accesso al livello dell'abbonamento specificato. In altre parole, il membro ha continuamente accesso al livello da questa data e ora. Tieni presente che diversi periodi dell'abbonamento potrebbero essere stati spesi a livelli dell'abbonamento più elevati.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
Il numero di mesi, arrotondati per difetto al numero intero più vicino, per i quali l'utente ha avuto accesso al livello specificato. Il valore riflette il numero di mesi completi in cui il membro ha avuto accesso al livello, ma il numero non implica che il membro abbia continuato ad avere un proprio abbonamento attivo per un determinato periodo di tempo.