Pular para o conteúdo principal
Atenção Lançamos uma nova ferramenta de conformidade para a X API v2 chamada batch compliance. Essa ferramenta permite enviar grandes conjuntos de IDs de Posts ou de usuários para obter seu status de conformidade e determinar quais dados exigem ação para colocar seus conjuntos em conformidade.
Além disso, tanto o batch compliance quanto o firehose de conformidade foram atualizados para oferecer suporte a edições de Post. No firehose de conformidade, um novo evento ‘tweet_edit’ foi adicionado. Consulte a documentação de Compliance Data Objects para mais detalhes. Saiba mais sobre como o metadata de Edit Post funciona na página Edit Posts fundamentals.

​
Visão geral

Enterprise Um dos valores centrais da X é defender e respeitar a voz do usuário. Isso inclui respeitar suas expectativas e intenção quando eles excluem, modificam ou editam o conteúdo que escolhem compartilhar na X. Acreditamos que isso é fundamental para a saúde de longo prazo de uma das maiores plataformas públicas de informação em tempo real do mundo. A X coloca o controle nas mãos de seus usuários, dando às pessoas a capacidade de gerenciar sua própria experiência na X. Acreditamos que os consumidores corporativos que recebem dados da X têm a responsabilidade de honrar as expectativas e a intenção dos usuários finais. Para mais informações sobre os tipos de eventos de conformidade possíveis na plataforma X, consulte nosso artigo Honrando a intenção do usuário na X. Qualquer desenvolvedor ou empresa que consuma dados da X por meio de uma API tem a obrigação de envidar todos os esforços razoáveis para honrar alterações no conteúdo do usuário. Essa obrigação se estende a eventos do usuário, como exclusões, modificações e mudanças nas opções de compartilhamento (por exemplo, quando o conteúdo se torna protegido ou retido). Isso também inclui quando os usuários editam seus Posts. Consulte a redação específica na Política do Desenvolvedor e/ou no seu Acordo de Dados da X para entender como essa obrigação afeta seu uso de dados da X. A X oferece as seguintes soluções que fornecem informações sobre esses eventos de conformidade do usuário e indicam se um Post ou usuário específico está ou não disponível publicamente. Uma breve visão geral das soluções e seus padrões gerais de integração é apresentada abaixo:

​
GET statuses/lookup e GET users/lookup

  • Formato: APIs REST. Consulte: GET statuses/lookup e GET users/lookup.
  • Esses endpoints sempre retornam a versão mais recente de quaisquer edições de Post. Todos os Objetos Post que descrevem Posts criados após a introdução do recurso de edição incluirão metadata de edição de Post. Isso vale mesmo para Posts que não foram editados.
  • Para todos os Posts, solicitações feitas mais de 30 minutos após a criação representarão o estado final de todos os Posts.
  • Fornecem informações de disponibilidade para Posts ou usuários específicos, conforme definido pelo solicitante como parte da solicitação à API.
  • Podem ser usados para verificações pontuais ad hoc do estado atual de disponibilidade de um grupo específico de Posts/usuários.
  • Ideal para clientes que precisam verificar o estado atual de um Post ou usuário específico em um determinado momento.
  • Essas APIs fornecem um mecanismo útil que pode ser usado por clientes que precisam verificar a disponibilidade de um conteúdo, por exemplo, quando:
    1. Exibindo Posts
    2. Interagindo com um(a) Post ou usuário de forma 1:1
    3. Distribuindo Conteúdo da X para um terceiro por meio de um download de arquivo permitido
    4. Armazenando Posts por períodos prolongados

​
Compliance Firehose (apenas para Enterprise)

  • Formato: API de streaming. Consulte: Compliance Firehose.
  • Fornece um stream em tempo real de atividades de compliance no X. Essas atividades incluem edições de Posts.
  • Pode ser usado para manter o estado de conformidade em um conjunto de dados armazenados à medida que novos eventos de conformidade ocorrem na plataforma.
  • Ideal para clientes que consomem e armazenam grandes volumes de dados do X por períodos prolongados.

​
Guias

​
Melhores práticas de compliance

​
Recomendações e melhores práticas

  • Crie esquemas de armazenamento de dados que guardem o ID numérico do Post e o ID do Usuário: Mensagens relacionadas ao usuário exigem ações em todos os Posts desse Usuário. Portanto, como todas as mensagens de conformidade são entregues apenas por ID numérico, é importante projetar esquemas de armazenamento que mantenham o relacionamento entre Post e Usuário com base em IDs numéricos. Consumidores de dados precisarão monitorar eventos de conformidade tanto pelo ID do Post quanto pelo ID do Usuário e conseguir atualizar o repositório de dados local de forma apropriada.
  • Crie esquemas que contemplem todos os status de conformidade: Dependendo de como as atividades de conformidade serão tratadas em diferentes aplicações, pode ser necessário adicionar outros metadados ao repositório de dados. Por exemplo, consumidores de dados podem decidir adicionar metadados a um banco de dados existente para facilitar a restrição da exibição de conteúdo em países afetados por uma mensagem status_withheld.
  • Tratamento de exclusões de Retweet: Retweets são um tipo especial de Post em que a mensagem original está aninhada em um objeto dentro do Retweet. Nesse caso, há dois IDs de Post referenciados em um Retweet — o ID do Retweet e o ID da mensagem original (incluída no objeto aninhado). Quando a mensagem original é excluída, uma mensagem de DELETE de Post é emitida para o ID original. Eventos de exclusão de Post normalmente acionam eventos de DELETE para todos os Retweets. No entanto, em alguns casos, nem todos são enviados, e os sistemas clientes devem tolerar exclusões de Retweet incompletas. A exclusão do ID original deve ser suficiente para excluir todos os Retweets subsequentes. É uma prática recomendada referenciar o ID do Post original ao armazenar Retweets e excluir todos os Retweets referenciados ao receber eventos de DELETE de Post.

​
Objetos de Conformidade data

​
Compliance Firehose API

Os possíveis tipos de eventos de conformidade incluem eventos de Post (ou “status”) e eventos de Usuário, para os quais há vários tipos descritos abaixo.   Observação:
  • Leia mais sobre os status de Usuário aqui e sobre nossa política para desenvolvedores a respeito de Posts excluídos aqui.
  • O Compliance Firehose foi atualizado para fornecer eventos ‘tweet_edit’. 
  • Vários eventos de exclusão, proteção e suspensão de Usuário não são necessariamente permanentes e podem alternar entre estados indefinidamente. Isso inclui: user_delete, user_undelete, user_protect, user_unprotect e user_suspend, user_unsuspend.
  • User_deletes são seguidos por status_deletes 30 dias depois apenas se o usuário não tiver optado por user_undelete na conta. É possível que um user_delete seja revertido pelo usuário e que as exclusões de todos os seus Posts 30 dias depois não ocorram.
  • User_suspend é uma ação que permanece válida, a menos que o usuário seja submetido a um evento user_unsuspend. Esses casos não estão sujeitos a alterações dentro de um período de 30 dias.
Consulte a coluna ‘Ação Recomendada’ para entender como processar cada tipo de evento, de modo a respeitar a privacidade e a intenção do usuário final.
Tipo de Mensagem OriginalObjetoPermanente (Sim/Não)Ação Recomendada
deleteStatusSimExcluir o Post associado.
status_withheldStatusSimSuprimir o Post associado nos países específicos listados na mensagem status_withheld.
dropStatusNãoRemover o Post da visualização pública.
undropStatusNãoO status pode voltar a ser exibido e tratado como público.
tweet_editStatusSimRespeitar e, quando relevante, exibir a nova edição.
user_deleteUserNãoSuprimir ou excluir todos os Posts do usuário associado.
user_undeleteUserNãoTodos os Posts do usuário associado podem voltar a ser exibidos e tratados como públicos.
user_protectUserNãoSuprimir ou excluir todos os Posts do usuário associado.
user_unprotectUserNãoTodos os Posts do usuário associado podem voltar a ser exibidos e tratados como públicos.
user_suspendUserNãoSuprimir ou excluir todos os Posts do usuário associado.
user_unsuspendUserNãoTodos os Posts do usuário associado podem voltar a ser exibidos e tratados como públicos.
scrub_geoUserSimExcluir todos os geodados fornecidos pela X para todos os Posts do usuário anteriores ao Post especificado na mensagem scrub_geo. Observe que Posts subsequentes de um usuário podem conter geodados que podem ser usados.
user_withheldUserSimSuprimir os Posts do usuário associado nos países específicos listados na mensagem user_withheld.
deleteFavoriteSimExcluir o like/favorito associado.

​
Exemplos de payload

Veja abaixo exemplos de payload para cada evento de conformidade descrito na tabela acima. Edição de Post 
{"tweet_edit":
   {
     "id": "1557445923210514432"
     "initial_tweet_id": "1557433858676740098",
     "edit_tweet_ids": ["1557433858676740098", "1557445923210514432"],
     "timestamp_ms": "1660155761384"
   }
 }
Excluir Post
{
  "delete": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
Post retido
{
  "status_withheld": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220608",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestamp_ms": "1432228155593"
  }
}
Soltar
{
  "drop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}
Reverter exclusão
{
  "undrop": {
    "status": {
      "id": 601430178305220600,
      "id_str": "601430178305220600",
      "user_id": 3198576760,
      "user_id_str": "3198576760"
    },
    "timestamp_ms": "1432228155593"
  }
}

​
Limpar dados geográficos

{
  "scrub_geo": {
    "user_id": 519761961,
    "up_to_status_id": 411552403083628540,
    "up_to_status_id_str": "411552403083628544",
    "user_id_str": "519761961",
    "timestamp_ms": "1432228180345"
  }
}
Exclusão de usuário
{
  "user_delete": {
    "id": 771136850,
    "timestamp_ms": "1432228153548"
  }
}
Reativação de usuário
{
  "user_undelete": {
    "id": 796250066,
    "timestamp_ms": "1432228149062"
  }
}
Usuário retido por restrição
{
  "user_withheld": {
    "user": {
      "id": 1375036644,
      "id_str": "1375036644"
    },
    "withheld_in_countries": [
      "XY"
    ],
    "timestampMs": "2014-08-27T23:49:41.839+00:00"
  }
}
Proteção do usuário
{
  "user_protect": {
    "id": 3182003550,
    "timestamp_ms": "1432228177137"
  }
}
Remover proteção de usuário
{
  "user_unprotect": {
    "id": 2911076065,
    "timestamp_ms": "1432228180113"
  }
}
Suspensão de usuário
{
  "user_suspend": {
    "id": 3120539094,
    "timestamp_ms": "1432228194217"
  }
}
Reativar usuário
{
  "user_unsuspend": {
    "id": 3293130873,
    "timestamp_ms": "1432228193828"
  }
}

​
integrando o Compliance Firehose

O Compliance Firehose é uma API de stream em tempo real que entrega eventos de conformidade que ocorrem na plataforma X. Para entender os eventos de conformidade e como eles são gerados no X, consulte nosso artigo Honoring User Intent on X. É importante observar que eventos de Post e de usuário são entregues de forma independente e que cada um deve ser processado separadamente (ou seja, a exclusão de um Post não implica um evento de usuário e vice-versa). Vários eventos de usuário não são necessariamente permanentes e podem alternar entre estados indefinidamente. Isso inclui: user_delete, user_undelete, user_protect, user_unprotect, user_suspend e user_unsuspend. User_deletes são seguidos por status_deletes 30 dias depois apenas se o usuário não tiver optado por user_undelete na conta. É possível que um user_delete seja revertido pelo usuário e que as exclusões de todos os seus Posts 30 dias depois não ocorram. User_suspend é uma ação que permanece ativa a menos que o usuário seja submetido a um evento user_unsuspend. Esses casos não estão sujeitos a alterações em um período de 30 dias. Nunca é apropriado exibir eventos de conformidade diretamente aos usuários do seu software ou incorporá-los de qualquer forma aos seus produtos ou experiências do cliente. Eles se destinam exclusivamente a manter a conformidade e a respeitar as ações dos usuários do X.

​
Integração com o Compliance Firehose

Para integrar o Compliance Firehose ao seu sistema, você precisará criar uma integração capaz de:
  1. Estabelecer uma conexão de stream com cada partição da API de stream do Compliance Firehose
  2. Lidar com altos volumes de dados — desacoplando a ingestão do stream do processamento adicional por meio de processos assíncronos
  3. Reconectar-se automaticamente às partições do stream quando houver desconexão por qualquer motivo
  4. Processar eventos de compliance relevantes para os dados de Post e de Usuário que você armazenou, de acordo com as orientações acima

​
Honrando a intenção do usuário no X

Acreditamos que respeitar a privacidade e a intenção dos usuários do X é fundamental para a saúde de longo prazo de uma das maiores plataformas públicas de informação em tempo real do mundo. O X coloca os controles de privacidade nas mãos de seus usuários, dando às pessoas a capacidade de controlar sua própria experiência no X. Como consumidores corporativos de dados do X, temos a responsabilidade coletiva de respeitar a privacidade e as ações dos usuários finais para manter esse ambiente de confiança e respeito. Há uma variedade de situações que podem ocorrer com Posts e contas de usuário que afetam como são exibidos na plataforma. As ações que impactam privacidade e intenção são definidas nos níveis de Status (Post) e de usuário. Essas ações incluem:

​
Usuário

AçãoDescrição
Proteger contaUm usuário do X pode proteger ou remover a proteção da sua conta a qualquer momento. Contas protegidas exigem aprovação manual do usuário para cada pessoa autorizada a visualizar os Posts da conta. 
Para mais informações, consulte Sobre Posts públicos e protegidos.
Excluir contaUm usuário do X pode decidir excluir sua conta e todas as mensagens de status associadas a qualquer momento. O X mantém as informações da conta por 30 dias após a exclusão caso o usuário decida reverter a exclusão e reativar sua conta.
Remover dados de localizaçãoUm usuário do X pode remover todos os dados de localização de Posts anteriores a qualquer momento. Isso é conhecido como “scrub geo”.
Suspender contaO X se reserva o direito de suspender contas que violem as Regras do X ou quando houver suspeita de invasão ou comprometimento. Suspensões de conta só podem ser revertidas (cancelar suspensão) pelo X.
Reter contaO X se reserva o direito de reter reativamente o acesso a determinados conteúdos em um país específico de tempos em tempos. Uma conta retida só pode ser liberada pelo X. 
Para mais informações, consulte Conteúdo retido por país.

​
Status

AçãoDescrição
Excluir statusUm usuário do X pode excluir um status a qualquer momento. Status excluídos não podem ser desfeitos e são permanentemente removidos.
Reter statusA X reserva-se o direito de reter, de forma reativa, o acesso a determinados conteúdos em um país específico de tempos em tempos. Um status retido só pode ser liberado pela X. 
Para mais informações, consulte Conteúdo retido por país.

​
Acompanhando alterações de Usuário e Status

O estado de um Usuário ou Status pode mudar a qualquer momento devido a uma das ações acima, o que afeta a forma como os consumidores de dados da X devem tratar a disponibilidade e a privacidade de todo o conteúdo associado. Quando essas ações ocorrem, é enviada uma mensagem de conformidade correspondente indicando que o estado de um Status ou Usuário foi alterado.

​
Referência da API

​
GET compliance/firehose

​
Métodos

MétodoDescrição
GET /compliance/:streamConectar ao stream de dados

​
Autenticação

Todas as requisições para a Compliance Firehose API devem usar autenticação HTTP Basic, composta por uma combinação válida de endereço de e-mail e senha usada para acessar sua conta em console.gnip.com. As credenciais devem ser enviadas no cabeçalho Authorization de cada requisição.

​
GET /compliance/:stream

Estabelece uma conexão persistente com o stream de dados Compliance firehose, por meio da qual os eventos de conformidade serão entregues.
Request MethodHTTP GET
Connection TypeKeep-Alive
URLDisponível na página de Ajuda da API do stream no seu painel e com a seguinte estrutura:


https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1

Observação: o parâmetro “partition” é obrigatório. Você precisará se conectar às 8 partições, cada uma contendo 12,5% do volume total, para consumir o stream completo.
CompressionGzip. Para se conectar ao stream usando compactação Gzip, basta enviar um cabeçalho Accept-Encoding na solicitação de conexão. O cabeçalho deve ser o seguinte:

Accept-Encoding: gzip
Character EncodingUTF-8
Response FormatJSON. O cabeçalho da solicitação deve especificar o formato JSON para a resposta.
Rate Limit10 solicitações a cada 60 segundos.
Read TimeoutDefina um tempo limite de leitura no cliente e certifique-se de que ele esteja acima de 30 segundos.
Support for Tweet editsTodas as edições de Tweet acionam um evento de Compliance “tweet_edit”. Consulte a documentação Compliance Data Objects para mais detalhes.
Example Curl Request A solicitação de exemplo a seguir é executada usando cURL na linha de comando: 
curl --compressed -v -uexample@customer.com "https://gnip-stream.x.com/stream/compliance/accounts/:account_name/publishers/twitter/:stream_label.json?partition=1"
Observação: a solicitação acima está conectando apenas em partition=1 do Compliance firehose — você precisará se conectar a todas as 8 partições para consumir todo este stream.

​
Códigos de resposta

As respostas a seguir podem ser retornadas pela API para essas solicitações. A maioria dos códigos de erro vem acompanhada de uma string com detalhes adicionais no corpo. Para respostas diferentes de 200, os clientes devem tentar reconectar.
StatusTextoDefinição
200SucessoA conexão foi aberta com sucesso e novas atividades serão enviadas conforme chegarem.
401Não autorizadoA autenticação HTTP falhou devido a credenciais inválidas. Faça login em console.gnip.com com suas credenciais para garantir que você as está usando corretamente na sua solicitação.
406Não aceitávelGeralmente ocorre quando o cliente não inclui corretamente os cabeçalhos para aceitar codificação gzip do stream, mas pode ocorrer em outras circunstâncias também. Conterá uma mensagem JSON semelhante a: “Esta conexão requer compactação. Para habilitar a compactação, envie um cabeçalho ‘Accept-Encoding: gzip’ na sua solicitação e esteja pronto para descompactar o stream conforme ele é lido no lado do cliente.”
429Limite de taxa excedidoSeu App excedeu o limite de solicitações de conexão.
503Serviço indisponívelProblema no servidor do X. Reconecte usando um padrão de recuo exponencial. Se nenhum aviso sobre esse problema tiver sido publicado na X API Status Page, entre em contato com o suporte.

​
Outras recomendações e melhores práticas

  • Crie esquemas de armazenamento de dados que guardem o ID numérico do Tweet e o ID do usuário: Mensagens relacionadas a um usuário exigem ação em todos os Tweets desse usuário. Portanto, como todas as mensagens de conformidade são entregues apenas por ID numérico, é importante projetar esquemas de armazenamento que mantenham o relacionamento entre Tweet e usuário com base em IDs numéricos. Os consumidores de dados precisarão monitorar eventos de conformidade tanto por ID de Tweet quanto por ID de usuário e conseguir atualizar o repositório de dados local de forma apropriada.
  • Crie esquemas que contemplem todos os statuses de conformidade: Dependendo de como as atividades de conformidade serão tratadas em diferentes aplicativos, pode ser necessário adicionar outros metadados ao repositório de dados. Por exemplo, os consumidores de dados podem decidir adicionar metadados a um banco de dados existente para facilitar a restrição da exibição de conteúdo em países afetados por uma mensagem status_withheld.
  • Tratamento de exclusões de Retweet: Retweets são um tipo especial de Tweet em que a mensagem original está aninhada em um objeto dentro do Retweet. Nesse caso, há dois IDs de Tweet referenciados em um Retweet — o ID do Retweet e o ID da mensagem original (incluída no objeto aninhado). Quando a mensagem original é excluída, é emitida uma mensagem de delete de Tweet para o ID original. Mensagens de delete subsequentes NÃO são emitidas para todos os Retweets. A exclusão do ID original deve ser suficiente para excluir todos os Retweets subsequentes.
⌘I