Members

Observação: desde 31 de março de 2020, o endpoint members substitui o endpoint sponsors, que foi descontinuado e não será mais compatível a partir de 30 de setembro de 2020. Os clientes de API precisam atualizar as chamadas para o método sponsors.list para que usem o método members.list.

Esse endpoint só pode ser usado por criadores de conteúdo para fazer solicitações aos próprios canais do YouTube com Clubes dos canais ativados. Entre em contato com seu representante do Google ou do YouTube para solicitar acesso.

Um recurso member representa um membro de um canal do YouTube. Um membro oferece apoio monetário recorrente ao criador de conteúdo e recebe benefícios especiais. Por exemplo, os membros podem conversar quando o criador ativa o modo exclusivo para membros no chat.

Métodos

A API oferece suporte aos seguintes métodos para recursos member:

list
Lista os membros (antes conhecidos como "patrocinadores") de um canal. A solicitação de API precisa ser autorizada pelo proprietário do canal.

Representação de recurso

A estrutura JSON a seguir mostra o formato de um recurso 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,
        }
      ]
    }
  }
}

Propriedades

A tabela a seguir define as propriedades que aparecem neste recurso:

Propriedades
kind string
Identifica o tipo de recurso da API. O valor será youtube#member.
etag etag
A Etag desse recurso.
snippet object
O objeto snippet contém detalhes sobre o membro.
snippet.creatorChannelId string
O ID do canal do YouTube do criador de conteúdo que oferece os Clubes dos canais.
snippet.memberDetails object
Esse objeto contém dados de perfil sobre o canal do YouTube que está pagando pela assinatura.

Um canal pode ter membros com dados de perfil indisponíveis. Por exemplo, isso ocorre com membros que excluíram os canais, mas ainda estão pagando pelas assinaturas. Observe que esses membros ainda poderão acessar os benefícios da assinatura.

As respostas da API incluem recursos para esses membros para garantir contagens precisas, mesmo que os detalhes do perfil dentro do objeto memberDetails não estejam definidos. O membershipsDetails ainda é fornecido para esses membros.
snippet.memberDetails.channelId string
O ID do canal do YouTube do canal membro. Se ele for definido, o ID do canal também poderá ser tratado como um identificador exclusivo para o membro. Se não for definido, o membro não poderá ser identificado exclusivamente, mas o recurso ainda transmitirá detalhes da associação, como os níveis que o membro pode acessar e a duração da associação.
snippet.memberDetails.channelUrl string
O URL do canal.
snippet.memberDetails.displayName string
O nome de exibição do canal.
snippet.memberDetails.profileImageUrl string
URL do avatar do canal.
snippet.membershipsDetails object
Esse objeto contém detalhes da assinatura do canal membro.
snippet.membershipsDetails.highestAccessibleLevel string
O ID do nível de assinatura mais alto que o canal membro pode acessar no momento. O valor corresponde ao valor da propriedade id em um recurso membershipsLevel.
snippet.membershipsDetails.highestAccessibleLevelDisplayName string
O nome do nível de assinatura mais alto que o canal membro pode acessar no momento. O valor corresponde ao valor da propriedade displayName em um recurso membershipsLevel.
snippet.membershipsDetails.accessibleLevels[] list (of strings)
Uma lista dos IDs de todos os níveis de assinatura que o usuário pode acessar no momento. A lista inclui o nível ativo no momento e todos os níveis abaixo dele.
snippet.membershipsDuration object
Esse objeto contém informações sobre a duração total da assinatura do membro atual, sem considerar os níveis de preço. A propriedade snippet.membershipsDetails.membershipsDurationAtLevel[] contém uma lista de objetos com detalhes sobre um período da assinatura em que o membro teve acesso a um nível de assinatura específico.

O exemplo a seguir mostra como essas propriedades funcionam: um membro compra uma nova assinatura em janeiro com o nível 1 e tem essa assinatura até março. Em abril e maio, o membro não terá uma assinatura. Em junho, o membro reinicia a assinatura, novamente no nível 1. Em agosto, ele faz upgrade da assinatura para o nível 2. Portanto, se uma chamada de API for feita em outubro, o recurso member conteria o seguinte: 
"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
A data e a hora em que a assinatura atual do membro começou. Em outras palavras, o membro tem uma associação contínua desde essa data e hora. Observe que períodos diferentes da assinatura podem ter sido gastos em níveis de assinatura diferentes.
snippet.membershipsDuration.memberTotalDurationMonths integer
O número de meses, arredondado para o número inteiro mais próximo, em que o usuário foi membro. O valor reflete o número de meses completos em que o membro teve uma assinatura, mas o número não implica que o membro teve uma assinatura continuamente por muitos meses.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[] list (of objects)
Uma lista de objetos. Cada objeto contém detalhes sobre um período da assinatura em que o membro teve acesso a um nível de assinatura específico. A lista inclui um objeto para cada nível de assinatura que o membro pode acessar no momento.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.level string
O ID do nível de assinatura. O valor corresponde ao valor da propriedade id em um recurso membershipsLevel.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberSince datetime
A data e a hora em que o membro teve acesso ao nível de assinatura especificado. Em outras palavras, o membro continua tendo acesso ao nível desde essa data e hora. Observe que períodos diferentes da assinatura podem ter sido gastos em níveis mais altos.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel.memberTotalDurationMonths integer
O número de meses, arredondado para o número inteiro mais próximo, em que o usuário teve acesso ao nível especificado. O valor reflete o número de meses completos em que o membro teve acesso ao nível, mas o número não implica que o membro teve uma assinatura continuamente por tantos meses.