Pular para o conteúdo principal

​
Como integrar com os endpoints de Timelines

Esta página contém informações sobre várias ferramentas e conceitos-chave que você deve conhecer ao integrar os endpoints de timelines ao seu sistema. Dividimos a página nas seguintes seções:

​
Ferramentas úteis

Antes de explorarmos alguns conceitos principais, recomendamos usar uma das ferramentas ou amostras de código abaixo para começar a testar a funcionalidade desses endpoints. Amostras de código Quer configurar esses endpoints com código na sua linguagem de programação preferida? Temos várias amostras de código disponíveis que você pode usar como ponto de partida em nossa página no GitHub. Bibliotecas Aproveite uma de nossas muitas bibliotecas de terceiros da comunidade para ajudar você a começar. Você pode encontrar uma biblioteca compatível com os endpoints v2 procurando pela tag de versão adequada. Postman O Postman é uma ótima ferramenta para testar esses endpoints. Cada requisição do Postman inclui todos os parâmetros de caminho e de corpo para ajudar você a entender rapidamente o que está disponível. Para saber mais sobre nossas coleções do Postman, visite a página Usando o Postman.

​
Conceitos-chave

Autenticação Todos os endpoints da X API v2 exigem que as requisições sejam autenticadas com um conjunto de credenciais, também conhecido como chaves e tokens. Você pode usar OAuth 1.0a User Context ou OAuth 2.0 Authorization Code com PKCE para autenticar requisições a esses endpoints. Você pode usar OAuth 2.0 App-Only para a timeline de Posts do usuário e a timeline de menções ao usuário. OAuth 1.0a User Context exige que você utilize suas API Keys, Access Tokens de usuário e um conjunto de outros parâmetros para criar um cabeçalho de autorização, que você então enviará junto com sua requisição. Os Access Tokens devem estar associados ao usuário em nome de quem você está fazendo a requisição. Se você quiser gerar um conjunto de Access Tokens para outro usuário, ele deverá autorizar sua App usando o fluxo OAuth de 3 etapas. Observe que OAuth 1.0a pode ser difícil de usar. Se você não estiver familiarizado com esse método de autenticação, recomendamos usar uma biblioteca, uma ferramenta como o Postman ou OAuth 2.0 para autenticar suas requisições. Se você quiser solicitar um Post ou metrics privadas desses endpoints, será necessário usar OAuth 1.0a User Context ou OAuth 2.0 Authorization Code com PKCE, o que garantirá que você tenha as permissões adequadas do usuário proprietário desse conteúdo. OAuth 2.0 App-Only exige apenas que você envie um OAuth 2.0 App Access Token junto com sua requisição. Você pode gerar um App Access Token diretamente em uma App de desenvolvedor ou gerar um usando o endpoint POST oauth2/token. Você pode usar isso para a timeline de Posts do usuário ou a timeline de menções ao usuário. OAuth 2.0 Authorization Code com PKCE permite maior controle sobre o escopo de uma aplicação e fluxos de autorização em vários dispositivos. OAuth 2.0 permite escolher escopos específicos e granulares que concedem permissões específicas em nome de um usuário. Para habilitar OAuth 2.0 na sua App, você deve ativá-lo nas configurações de autenticação da sua App, localizadas na seção de configurações da App no portal do desenvolvedor.
ObservaçãoSe você estiver solicitando os seguintes fields, OAuth 1.0a User Context ou OAuth 2.0 Authorization Code é obrigatório:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
Portal do desenvolvedor, Projetos e Apps de desenvolvedor Para trabalhar com quaisquer endpoints da X API v2, você deve inscrever-se para uma conta de desenvolvedor, configurar um Projeto nessa conta e criar uma App de desenvolvedor dentro desse Projeto. Suas chaves e tokens nessa App de desenvolvedor funcionarão para esses endpoints de timelines. Limites de requisições Todos os dias, muitos milhares de desenvolvedores fazem requisições à X API. Para ajudar a gerenciar o volume, limites de requisições são aplicados a cada endpoint, limitando o número de requisições que cada desenvolvedor pode fazer em nome de uma App ou em nome de um usuário autenticado. Há diferentes limites de requisições aplicados a esses endpoints dependendo de qual método de autenticação está sendo usado. Os limites em nível de app se aplicam a uma App fazendo requisições usando OAuth 2.0 App-Only, enquanto o limite em nível de usuário se aplica a requisições feitas em nome do usuário autorizador específico usando OAuth 1.0a User Context. Esses dois limites de requisições têm como base a frequência de requisições dentro de uma janela de 15 minutos. Por exemplo, um App usando autenticação OAuth 2.0 App-Only para ambos esses endpoints de timelines pode fazer 1500 solicitações (incluindo solicitações de paginação) para a timeline de Posts do usuário e 450 solicitações (incluindo solicitações de paginação) para a timeline de menções do usuário dentro de um período de 15 minutos. Esse mesmo App, dentro do mesmo período de 15 minutos, com dois usuários autorizados diferentes (usando Contexto de Usuário do OAuth 1.0a) pode fazer 900 solicitações (incluindo solicitações de paginação) para a timeline de Posts do usuário e 180 solicitações (incluindo solicitações de paginação) para a timeline de menções do usuário para cada usuário autenticado. A timeline inicial em ordem cronológica inversa tem um limite de taxa por usuário de 180 solicitações por janela de 15 minutos. Com este endpoint, você pode retornar todos os Posts criados em uma timeline nos últimos 7 dias, bem como os 800 mais recentes, independentemente da data de criação. Fields and expansions A X API v2 permite selecionar exatamente quais dados você quer que a API retorne usando fields e expansions. O parâmetro expansions permite incluir (expandir) objetos referenciados no payload. Por exemplo, este endpoint permite solicitar objetos de enquete (poll), lugar (place), mídia (media) e outros usando o parâmetro expansions. O parâmetro fields permite selecionar exatamente quais fields dentro dos diferentes objetos de dados você gostaria de receber. Por padrão, o Objeto Post principal retornado por esses endpoints inclui os fields id e text. Para receber fields adicionais, como author_id ou public_metrics, você terá que solicitá-los especificamente usando os parâmetros fields. Alguns fields importantes que você pode considerar na sua integração são nossos dados de enquete (poll), metrics, Post annotations e os fields de conversation ID. Adicionamos um guia sobre how to use fields and expansions em conjunto ao nosso X API v2 data dictionary. Post metrics Os endpoints da X API v2 permitem solicitar metrics de Post diretamente do Objeto Post retornado, desde que você inclua os fields apropriados na sua solicitação. Existem algumas limitações com metrics de Post das quais você deve estar ciente, especificamente relacionadas à privacidade do usuário e aos seguintes fields de resposta:
  • tweet.fields.non_public_metrics
  • tweet.fields.promoted_metrics
  • tweet.fields.organic_metrics
  • media.fields.non_public_metrics
  • media.fields.promoted_metrics
  • media.fields.organic_metrics
Os fields mencionados incluem private metrics data, o que significa que você deve ser autorizado pelo publicador do Post para recuperar esses dados em nome dele ao usar o endpoint de timeline de Posts do usuário; ou seja, você deve usar OAuth 1.0a User Context ou OAuth 2.0 Authorization Code Flow with PKCE. Por exemplo, para receber non_public_metrics para a timeline de Posts do usuário com ID 1234, você precisará incluir access tokens associados a esse usuário na sua solicitação. Você pode fazer com que os usuários autorizem seu App e recebam um conjunto de access tokens associados a eles usando o fluxo OAuth de 3 etapas. Se você estiver usando a timeline de menções do usuário, os fields mencionados não estarão disponíveis, a menos que o autor que mencionou tenha autorizado seu App a acessar seus private metrics data e você esteja usando os access tokens desse usuário ao fazer a solicitação com Contexto de Usuário do OAuth 1.0a. Todos os non_public_metrics, organic_metrics e promoted_metrics estão disponíveis apenas para Posts criados nos últimos 30 dias. Isso significa que, quando você solicitar os fields mencionados, os resultados serão ajustados automaticamente para incluir apenas Posts dos últimos 30 dias. Se esses fields mencionados forem solicitados, apenas Posts que são de autoria do usuário autenticado serão retornados; todos os outros Posts receberão uma mensagem de erro. Pagination Esses endpoints utilizam paginação para que as respostas sejam retornadas rapidamente. Nos casos em que há mais resultados do que o que pode ser enviado em uma única resposta (até 100 Posts para os endpoints de timelines), você precisará paginar. Use o parâmetro max_results para definir quantos resultados serão retornados por página e o parâmetro pagination_token para retornar a próxima página de resultados. Você pode saber mais consultando nosso guia de paginação. Filtering results Esses endpoints incluem vários parâmetros que você pode usar para filtrar os resultados. Usando start_date e end_date, você pode restringir os resultados a um período específico. Se preferir usar IDs de Post para selecionar um conjunto específico de Posts, você pode usar since_id e until_id. A timeline de Posts do usuário também possui um parâmetro exclude que pode remover Retweets e respostas dos seus resultados.  Post caps e volume de Posts retornados Os endpoints de timeline de Post do usuário e timeline de menções do usuário têm um limite de Posts que podem retornar em um determinado mês. O endpoint de timeline inicial em ordem cronológica inversa não está sujeito a essa limitação. Independentemente de qual endpoint de timeline você use, os Posts retornados contarão para o Post cap no nível do Projeto. O uso é exibido no portal do desenvolvedor, e o “mês” começa no dia de renovação da sua assinatura exibido no dashboard do portal do desenvolvedor.  O endpoint de timeline de Post do usuário retornará apenas os 3200 Posts mais recentes publicados na timeline de um usuário. Ao definir start_time e end_time para um período que inclua Posts além dos 3200 mais recentes, você receberá uma resposta bem-sucedida, porém sem Posts. Também é importante observar que, se você passar excludes=replies nas suas solicitações de timeline de Post do usuário, apenas os 800 Posts mais recentes serão retornados. O endpoint de timeline de menções do usuário retornará apenas as 800 menções de Post mais recentes. O endpoint de timeline inicial em ordem cronológica inversa retorna os últimos 3200 Posts. Edições de Post Posts elegíveis para edição podem ser editados até cinco vezes nos 30 minutos após a publicação do Post original. Os endpoints de busca sempre fornecerão a versão mais recente do Post. Se você solicitar apenas Posts publicados há 30 minutos ou mais, sempre receberá a versão final do Post. No entanto, se você tiver um caso de uso quase em tempo real e estiver consultando Posts publicados nos últimos trinta minutos, esses Posts podem ter sido editados após você tê-los recebido. Esses Posts podem ser reidratados com busca ou com o endpoint de Post Lookup para confirmar seu estado final. Para saber mais sobre como funcionam as edições de Post, consulte a página Fundamentos de edição de Posts.   Casos extremos
  • Ao solicitar non_public_metrics no endpoint User Post timeline para Posts com mais de 30 dias, você pode ver um next_token na resposta com contagem de resultados igual a 0. Para evitar esse problema, garanta que o período solicitado com o parâmetro non_public_metrics esteja dentro dos 30 dias mais recentes. Além disso, o valor mínimo de max_results deve ser 10. Essas medidas podem ajudar a evitar esse cenário, mas isso ainda pode ocorrer.
  • Solicitar metrics de promoção para Posts que não foram promovidos retorna uma resposta vazia, em vez de data do Post. Nossa equipe está trabalhando para corrigir esse problema.
  • Para um Retweet que contém texto do corpo do Post com mais de 140 caracteres, o campo text será truncado em vez de retornar o texto completo do Post. A solução de curto prazo é expandir o Post referenciado e recuperar o texto completo a partir da expansão. Este é um bug que corrigiremos no futuro.
Próximas etapas [Faça sua primeira solicitação a um endpoint de Timelines]/x-api/posts/timelines#getting-started-with-reverse-chronological-home-timeline “Faça sua primeira solicitação a um endpoint de Timelines”) Veja a lista completa de parâmetros, fields e mais em nossas páginas de Referência da API Obtenha suporte ou solucione um erro
⌘I