Pular para o conteúdo principal

​
Como integrar aos endpoints de Search Posts

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

​
Ferramentas úteis

Antes de começarmos a explorar alguns conceitos-chave, recomendamos usar uma das seguintes ferramentas ou exemplos de código para começar a testar a funcionalidade desses endpoints.

​
Exemplos de código

Interessado em configurar esses endpoints com código na sua linguagem de programação preferida? Temos vários exemplos de código disponíveis que você pode usar como ponto de partida na nossa página no GitHub, incluindo um cliente Python e um cliente Ruby.

​
Bibliotecas

Aproveite uma de nossas diversas bibliotecas de terceiros da comunidade para começar. Você pode encontrar uma biblioteca compatível com os endpoints da v2 procurando pela tag de versão apropriada.

​
Postman

O Postman é uma ótima ferramenta para testar esses endpoints. Cada requisição do Postman inclui todos os parâmetros do endpoint em questão 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 principais

​
Autenticação

Todos os endpoints da X API v2 exigem que você autentique suas solicitações com um conjunto de credenciais, também chamadas de chaves e tokens. Você pode usar OAuth 1.0a User Context, OAuth 2.0 App-Only ou OAuth 2.0 Authorization Code with PKCE para autenticar suas solicitações ao endpoint de busca recente. Você deve usar OAuth 2.0 App-Only ao utilizar o endpoint de busca no arquivo completo. OAuth 2.0 App-Only exige apenas que você envie um OAuth 2.0 App Access Token com sua solicitação. Você pode gerar um App Access Token diretamente em um App do desenvolvedor ou gerar um usando o endpoint POST oauth2/token. OAuth 1.0a User Context exige que você utilize suas API Keys, Tokens de Acesso do usuário e alguns outros parâmetros para criar um cabeçalho de autorização, que você então enviará com sua solicitação. Os Tokens de Acesso devem estar associados ao usuário em nome de quem você está fazendo a solicitação. Se você deseja gerar um conjunto de Tokens de Acesso para outro usuário, esse usuário deve autorizar seu App usando o fluxo OAuth de 3 etapas. Observe que o 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 o OAuth 2.0 para autenticar suas solicitações. Se você deseja solicitar um Post ou métricas privadas desses endpoints, será necessário usar OAuth 1.0a User Context ou OAuth 2.0 Authorization Code with PKCE, o que garantirá que você tenha as permissões adequadas do usuário proprietário desse conteúdo. OAuth 2.0 Authorization Code with PKCE permite maior controle sobre o escopo de uma aplicação e fluxos de autorização em vários dispositivos. O OAuth 2.0 permite escolher escopos específicos e granulares que concedem permissões específicas em nome de um usuário. Para habilitar o OAuth 2.0 no seu App, você deve ativá-lo nas configurações de autenticação do seu App, encontradas na seção de configurações do App no portal do desenvolvedor.
ObserveSe você estiver solicitando os seguintes campos, é necessário OAuth 1.0a User Context ou OAuth 2.0 Authorization Code:
  • 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 do desenvolvedor Para trabalhar com quaisquer endpoints da X API v2, você deve ter criado uma conta de desenvolvedor, configurado um Projeto nessa conta e criado um App do desenvolvedor dentro desse Projeto. Suas chaves e tokens nesse App do desenvolvedor funcionarão com esses endpoints de pesquisa. Você pode usar chaves e tokens de um Projeto com qualquer nível de acesso para fazer solicitações ao endpoint de pesquisa recente. No entanto, será necessário usar um Projeto com nível de acesso Pro ou Enterprise para fazer solicitações ao endpoint de pesquisa do arquivo completo. Se você tiver acesso Enterprise, terá acesso a funcionalidades adicionais, incluindo mais operadores disponíveis e consultas mais longas.  

​
Limites de taxa

Todos os dias, milhares de desenvolvedores fazem requisições à X API. Para ajudar a gerenciar o volume, limites de taxa são aplicados a cada endpoint, limitando o número de requisições que cada desenvolvedor pode fazer em nome de um app ou de um usuário autenticado. Há diferentes limites de taxa aplicados a esses endpoints, dependendo do método de autenticação utilizado. Os limites de taxa em nível de app se aplicam a um app que faz requisições usando OAuth 2.0 App-Only, enquanto o limite de taxa em nível de usuário se aplica a requisições feitas em nome do usuário concedente específico usando OAuth 1.0a User Context ou OAuth 2.0 Authorization Code with PKCE. Esses dois limites de taxa são baseados na 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 fazer requisições ao endpoint de busca recente pode fazer 450 requisições (incluindo requisições de paginação) dentro de um período de 15 minutos. Esse mesmo app, no mesmo período de 15 minutos e com dois usuários autenticados diferentes (usando OAuth 1.0a User Context ou OAuth 2.0 Authorization Code with PKCE), pode fazer até 180 requisições (incluindo requisições de paginação) ao endpoint de busca recente para cada usuário autenticado.  

​
Campos e expansões

A X API v2 permite selecionar exatamente quais dados você quer receber da API usando campos e expansões. O parâmetro expansions permite expandir objetos referenciados no payload. Por exemplo, este endpoint permite solicitar objetos de enquete, local, mídia e outros usando o parâmetro expansions. Os parâmetros fields permitem selecionar exatamente quais campos, dentro dos diferentes objetos de dados, você deseja receber. Por padrão, o objeto principal de Post retornado por esses endpoints inclui os campos id e text (além de edit_history_tweet_ids para Posts criados após o lançamento desse recurso). Para receber campos adicionais, como author_id ou public_metrics, você precisará solicitá-los explicitamente usando os parâmetros fields. Alguns campos importantes que você pode considerar usar na sua integração são nossos dados de enquete, métricas, anotações de Post e campos de conversation ID. Adicionamos ao nosso dicionário de dados da X API v2 um guia sobre como usar fields e expansions juntos.  

​
Métricas

Os endpoints da X API v2 permitem solicitar métricas diretamente dos objetos retornados, desde que você forneça os campos apropriados na sua solicitação. Existem algumas limitações nas métricas de Posts das quais você deve estar ciente, especificamente relacionadas à privacidade do usuário e aos seguintes campos 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 campos mencionados incluem dados de métricas privadas, o que significa que você deve estar autorizado pelo autor do Post para recuperar esses dados em nome dele ao usar o endpoint de busca recente, ou seja, você deve usar OAuth 1.0a User Context. Como esse método de autenticação só pode ser usado com a busca recente, não será possível recuperar essas métricas por meio do endpoint de busca em arquivo completo. Por exemplo, para receber non_public_metrics dos Posts do usuário com id 1234, você precisará incluir Tokens de Acesso associados a esse usuário na sua solicitação. Você pode fazer com que os usuários autorizem seu app e receber um conjunto de Tokens de Acesso associados a eles usando o fluxo OAuth de 3 etapas. Todas as non_public_metrics, organic_metrics e promoted_metrics estão disponíveis apenas para Posts criados nos últimos 30 dias. Isso significa que, ao solicitar os campos mencionados, os resultados serão ajustados automaticamente para incluir apenas Posts dos últimos 30 dias. Se esses campos mencionados forem solicitados, somente Posts de autoria do usuário autenticado serão retornados; todos os demais Posts receberão uma mensagem de erro.  

​
Criando consultas de pesquisa

O principal recurso desses endpoints é o uso de uma única consulta de pesquisa para filtrar os Posts entregues a você. Essas consultas são compostas por operadores que correspondem a atributos de Post e de usuário, como palavras-chave da mensagem, hashtags e URLs. Os operadores podem ser combinados em consultas com lógica booleana e parênteses para ajudar a refinar o comportamento de correspondência da consulta. Você pode consultar nosso guia sobre como criar uma consulta para saber mais. Esses endpoints usam paginação para que as respostas sejam retornadas rapidamente. Quando houver mais resultados do que o possível em uma única resposta (até 100 Posts na busca recente e 500 na busca no arquivo completo), será necessário paginar. Use o parâmetro max_results para definir quantos resultados serão retornados por página e o parâmetro pagination_token para obter a próxima página de resultados. Saiba mais em nosso guia de paginação.

​
Limites de Posts

Os endpoints de Search Posts têm um limite de quantidade de Posts que podem retornar em um determinado mês, independentemente da paginação. Independentemente de qual endpoint de pesquisa você usar, os Posts retornados contarão para os limites de Posts 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 mostrado no dashboard do portal do desenvolvedor. Edições de Post Posts que são 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 pesquisa sempre fornecerão a versão mais recente do Post. Se você solicitar apenas Posts que foram publicados há 30 minutos ou mais, você 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 30 minutos, esses Posts podem ter sido editados após você tê-los recebido. Esses Posts podem ser reidratados com a pesquisa ou com o endpoint 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ções de Post.   Próximas etapas Faça sua primeira solicitação a um endpoint de Search Posts Veja a lista completa de parâmetros, campos e mais em nossas páginas de Referência da API Obtenha suporte ou solucione um erro