Guia de início rápido

​

Introdução aos endpoints de stream filtrado

Este guia de Introdução rápida ajudará você a fazer sua primeira solicitação ao grupo de endpoints de stream filtrado usando uma chamada cURL. cURL é uma ferramenta de linha de comando que permite fazer solicitações com configuração mínima.

Se você quiser ver exemplos de código em diferentes linguagens, visite nosso repositório no GitHub: X API v2 sample code. 

Pré-requisitos

Para concluir este guia, você precisará de um conjunto de chaves e tokens para autenticar sua solicitação. Você pode gerar essas chaves e tokens seguindo estas etapas:

• Inscreva-se para uma conta de desenvolvedor e aguarde a aprovação.
• Crie um Projeto e um App de desenvolvedor associado no portal do desenvolvedor.
• Acesse a página “Keys and tokens” do seu App para gerar as credenciais necessárias. Certifique-se de salvar todas as credenciais em um local seguro.

​

Etapas para criar uma solicitação de stream filtrado usando cURL

Etapa um: criar uma regra

As regras são compostas por um ou vários operadores, combinados com lógica booleana e parênteses para definir quais Posts serão entregues ao seu stream. Neste guia, vamos filtrar o stream para encontrar Posts que contenham a palavra-chave “cat” e também imagens. Aqui está a nossa regra:

has:images

Etapa dois: adicione uma tag à sua regra

Você pode adicionar várias regras simultâneas ao seu stream. Ao abrir sua conexão de streaming, Posts que correspondam a qualquer uma dessas regras passarão pela mesma conexão. Para garantir que você saiba qual Post corresponde a qual regra, você pode enviar uma tag junto com a solicitação de criação da regra. Cada Post que corresponder a essa regra incluirá um campo tag no payload do Post indicando a qual regra ele correspondeu. Para esta regra, vamos atribuir a seguinte tag:

with images

Terceiro passo: adicione sua regra ao stream

Este endpoint exige que você envie um corpo application/JSON junto com esta solicitação, contendo sua regra e sua tag. Você também notará que incluímos o valor da regra e a tag dentro de um objeto add, pois estamos adicionando essa regra ao stream. Este corpo JSON terá a seguinte aparência:

{
  "add": [
    {
      "value": "cat has:images",
      "tag": "gatos com imagens"
    }
  ]
}

Agora que você concluiu a configuração deste corpo JSON, você pode adicioná-lo a uma solicitação cURL, que ficará como a seguir. Esta solicitação ainda não está pronta, então aguarde para enviá-la até uma etapa posterior.

curl -X POST 'https://api.x.com/2/tweets/search/stream/rules' \
-H "Content-type: application/json" \
-H "Authorization: Bearer $APP_ACCESS_TOKEN" -d \
'{
  "add": [
    {"value": "cat has:images", "tag": "gatos com imagens"}
  ]
}'`

Etapa quatro: Autentique sua solicitação

Como os endpoints de regras do stream filtrado exigem autenticação OAuth 2.0 App-Only, você precisará substituir $APP_ACCESS_TOKEN no comando cURL da etapa três pelo App Access Token que você gerou nos pré-requisitos. 

Etapa cinco: Adicione sua regra ao stream

O próximo passo é executar sua solicitação cURL, o que adicionará a regra ao seu stream. Copie e cole o comando cURL na sua interface de linha de comando e pressione Enter. 

Se sua solicitação cURL foi bem-sucedida, você receberá uma resposta contendo dados sobre seu value, tag e id (serve como um identificador exclusivo para sua regra). Essa resposta será semelhante a isto:

{
  "data": [
    {
      "value": "cat has:images",
      "tag": "gatos com imagens",
      "id": "1273026480692322304"
    }
  ],
  "meta": {
    "sent": "2020-06-16T22:55:39.356Z",
    "summary": {
      "created": 1,
      "not_created": 0,
      "valid": 1,
      "invalid": 0
    }
  }
}

Você pode verificar se sua regra foi adicionada com sucesso enviando a seguinte solicitação GET para o endpoint de regras, certificando-se novamente de substituir $APP_ACCESS_TOKEN pelo seu token. Essa solicitação retornará a lista completa de todas as regras que foram adicionadas ao seu stream.

curl -X GET 'https://api.x.com/2/tweets/search/stream/rules' \
-H "Authorization: Bearer $APP_ACCESS_TOKEN"

Se a sua solicitação cURL for bem-sucedida, você deverá receber o seguinte:

{
	"data": [{
		"id": "1273028376882589696",
		"value": "cat has:images",
		"tag": "gatos com imagens"
	}],
	"meta": {
		"sent": "2020-06-16T23:14:06.498Z"
	}
}

Sexto passo: Identifique e especifique quais fields você deseja recuperar

Se você se conectar ao stream após a etapa cinco, receberá os campos padrão do Objeto Post na sua resposta: id, text e edit_history_tweet_ids. Se quiser receber campos adicionais além desses, será necessário especificá-los na sua solicitação com os parâmetros fields e/ou expansions.

Para este exercício, solicitaremos três conjuntos diferentes de campos de objetos distintos:

1. O campo adicional tweet.created_at nos objetos Post primários.
2. Os campos padrão do objeto de usuário dos autores associados para os Posts retornados: id, name e username
3. O campo adicional user.created_at nos objetos de usuário associados.  

Para solicitar esses campos, você precisará passar o seguinte na sua solicitação:

Key	Value	Returned fields
tweet.fields	created_at	tweets.created_at
expansions	author_id	includes.users.id, includes.users.name, includes.users.username
user.fields	created_at	includes.users.created_at

Agora que você sabe disso, você pode montar sua URL de solicitação para se conectar ao stream, que ficará assim:

https://api.x.com/2/tweets/search/stream?tweet.fields=created_at&expansions=author_id&user.fields=created_at

Sétimo passo: Conecte-se ao stream e revise sua resposta

Agora que sua regra está definida e você especificou quais fields deseja receber, você está pronto para se conectar ao stream, que entregará Objetos Post que correspondam à regra enviada. Veja como o comando cURL fica depois que você adiciona a URL do sexto passo à sua solicitação:

curl -X GET -H "Authorization: Bearer $APP_ACCESS_TOKEN" "https://api.x.com/2/tweets/search/stream?tweet.fields=created_at&expansions=author_id&user.fields=created_at"

Mais uma vez, esta requisição deve ser autenticada usando OAuth 2.0 App-Only; portanto, certifique-se de substituir $APP_ACCESS_TOKEN pelas suas credenciais antes de copiar e colar no seu terminal.

Depois de conectado ao stream filtrado, você começará a receber Posts que correspondem às suas regras no seguinte formato JSON:

{
  "data": [
    {
      "author_id": "2244994945",
      "created_at": "2022-09-14T19:00:55.000Z",
      "id": "1228393702244134912",
      "edit_history_tweet_ids": ["1228393702244134912"],
      "text": "O que o desenvolvedor escreveu no cartão do Dia dos Namorados?\n  \nwhile(true) {\n    I = Love(You);  \n}"
    },
    {
      "author_id": "2244994945",
      "created_at": "2022-09-12T17:09:56.000Z",
      "id": "1227640996038684673",
       "edit_history_tweet_ids": ["1227640996038684673"],
      "text": "Médicos: Pesquisar coisas online não te torna um médico\n\nDesenvolvedores: https://t.co/mrju5ypPkb"
    },
    {
      "author_id": "2244994945",
      "created_at": "2022-09-27T20:26:41.000Z",
      "id": "1199786642791452673",
      "edit_history_tweet_ids": ["1199786642791452673"],
      "text": "C#"
    }
  ],
  "includes": {
    "users": [
      {
        "created_at": "2013-12-14T04:35:55.000Z",
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
      }
    ]
  }
}

Se você quiser encerrar a conexão, pressione Ctrl+C na sua ferramenta de linha de comando em sistemas macOS ou Windows para interrompê-la, ou simplesmente feche a janela.