Members

Observação: a partir de 31 de março de 2020, o endpoint members substituirá o endpoint sponsors, que foi descontinuado e não terá mais suporte a partir de 30 de setembro de 2020. Os clientes da API precisam atualizar as chamadas para o método sponsors.list para usar members.list.

Esse endpoint só pode ser usado por criadores individuais para fazer solicitações para o próprio canal do YouTube habilitado para os Clubes dos canais. 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 suporte monetário recorrente a um criador de conteúdo e recebe benefícios especiais. Por exemplo, os membros podem conversar quando o criador de conteúdo ativa o modo somente para um chat.

Métodos

A API é compatível com os seguintes métodos para recursos member:

list
Lista os membros (anteriormente chamados de "patrocinadores") de um canal. A solicitação da 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 do recurso da API. O valor será youtube#member.
etag etag
A ETag deste 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 o canal, mas ainda pagam pelos Clubes dos canais. Esses membros ainda têm acesso aos benefícios da assinatura.

As respostas da API incluem recursos para esses membros com o objetivo de 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. Se definido, o ID do canal também pode 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 assinatura, 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
O URL do avatar do canal.
snippet.membershipsDetails object
Esse objeto contém detalhes da assinatura para o canal do 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 de 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 associação do membro atual sem considerar os níveis de preços. A propriedade snippet.membershipsDetails.membershipsDurationAtLevel[] contém uma lista de objetos com detalhes sobre um período de associação em que o membro teve acesso a um determinado nível de assinatura.

O exemplo a seguir mostra como essas propriedades funcionam: um assinante compra uma nova assinatura em janeiro no nível 1 de janeiro e a mantém até março. Em abril e maio, o membro não tem uma assinatura. Em junho, o membro reinicia a assinatura no nível 1. Em agosto, o membro fez upgrade da assinatura para o nível 2. Assim, se uma chamada de API for feita em outubro, o recurso member conterá 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
Data e hora em que a assinatura do assinante começou. Em outras palavras, o membro sempre teve uma assinatura desde essa data e hora. Observe que diferentes períodos podem ter sido gastos em diferentes níveis.
snippet.membershipsDuration.memberTotalDurationMonths integer
O número de meses, arredondado para o número inteiro mais próximo, de que o usuário é 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 ele tenha uma assinatura contínua por muitos meses.
snippet.memberDetails.membershipsDetails.membershipsDurationAtLevel[] list (of objects)
Lista de objetos, em que cada objeto contém detalhes sobre um período em que o membro teve acesso a um determinado nível de assinatura. 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 no nível da 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 da assinatura especificado. Em outras palavras, o membro sempre teve acesso ao nível desde essa data e hora. Observe que diferentes períodos de 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, que o usuário teve acesso ao nível especificado. O valor reflete o número de meses completos que o membro teve acesso ao nível, mas o número não implica que ele teve uma assinatura contínua durante esse período.