Twitter流和搜索API抓取器

导航

验证详情

这些详情已由PyPI 验证
维护者
来自gravatar.com的bmaz头像 bmaz 来自gravatar.com的boogheta头像 boogheta

未验证详情

这些详情尚未由PyPI 验证
项目链接
元数据
  • 许可证： GPL-3.0
  • 作者： Benjamin Ooghe-Tabanou
  • 标签 twitter
  • 要求： Python >=3.7

项目描述

DOI

logo logo

一个用于长期收集推文的命令行工具。喷绘机结合两种方法从Twitter API收集推文（“搜索”和“过滤”）以最大化收集到的推文数量，并在连接错误或重新启动的情况下自动填充收集中的空白。它处理各种配置选项，如

Python >= 3.7 兼容。

为了完全使用此工具，您的Twitter API密钥必须在2022年4月29日之前创建。如果您的密钥是在该日期之后创建的，喷绘机将仅与“搜索”端点一起工作，而不会与“过滤”端点一起工作。有关此问题的更多信息，请参阅Twitter的文档。

摘要

安装

  • 安装喷绘机

    pip install gazouilloire

  • 安装 Elasticsearch，版本 7.X（您也可以使用 Docker 来实现）

  • 在特定目录中初始化 gazouilloire 收集...

    gazou init path/to/collection/directory

  • ...或者在当前目录中

    gazou init

创建了一个 config.json 文件。打开它来配置收集参数。

快速入门

  • 设置您的 Twitter API 密钥 并生成相关的访问令牌

    "twitter": {
    "key": "<Consumer Key (API Key)>xxxxxxxxxxxxxxxxxxxxx",
    "secret": "<Consumer Secret (API Secret)>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "oauth_token": "<Access Token>xxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "oauth_secret": "<Access Token Secret>xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

  • 在 database 部分设置您的 ElasticSearch 连接（主机 & 端口），并选择一个将托管您语料库索引的数据库名称

    "database": {
    "host": "localhost",
    "port": 9200,
    "db_name": "medialab-tweets"
}

请注意，ElasticSearch 的数据库名称必须是小写，且不能包含任何空格或重音符号。

  • 将所需的 关键词 和 @用户 或/以及所需的 url_pieces 列表作为 JSON 数组写下

    "keywords": [
    "amour",
    "\"mots successifs\"",
    "@medialab_scpo"
],
"url_pieces": [
    "medialab.sciencespo.fr/fr"
],

    阅读下面的 高级设置 部分，以设置更多过滤器和选项或获取有关如何在关键词中正确编写查询的详细信息。

  • 通过在终端中键入以下命令开始收集

    gazou run

    或者，如果配置文件位于当前目录之外的其他目录中

    gazou run path/to/collection/directory

    阅读下面的 守护进程 部分，以让 gazouilloire 在服务器上持续运行并设置自动重启。

磁盘空间

在开始收集之前，您应该确保有足够的磁盘空间。每收集一千万条推文大约需要 1GB 的空间（不包括 图片和其他媒体内容）。

如果计划收集超过一亿条推文，您应考虑以 多索引模式 启动 gazouilloire，或者如果当前收集超过一亿五千万条推文，只需在新的文件夹和新的 db_name（即打开另一个 ElasticSearch 索引）中重新启动您的收集。

作为一个比较点，以下是 2021 年全年发送的包含某些关键词的推文数量（这些值是通过 API V2 推文计数 端点获得的）

查询 2021 年推文数量
lemondefr lang:fr 300 万
macron lang:fr 2100 万
vaccine 1.76 亿

将推文导出为 CSV 格式

数据存储在您的 ElasticSearch 中，您可以直接查询它。但是，您也可以轻松地将其导出为 CSV 格式

# Export all fields from all tweets, sorted in chronological order:
gazou export

排序推文

默认情况下，推文按照时间顺序排序，使用 "timestamp_utc" 字段。但是，您可以通过指定您不需要任何排序顺序来加快导出速度

gazou export --sort no

您还可以使用一个或多个其他排序键对推文进行排序

gazou export --sort collection_time

gazou export --sort user_id,user_screen_name

请注意

  • 按 "id" 排序是不可能的。
  • 按长文本字段（链接、地点名称、专有链接、文本、URL、用户描述、用户图像、用户位置、用户 URL）排序是不可能的。
  • 按其他 id 字段（如 "user_id" 或 "retweeted_id"）排序时，这些字段将按字母顺序排序（100、101、1000、99）而不是数字。
  • 按复数字段（例如提及、主题、域名）排序可能会产生意外的结果。
  • 按多个字段排序可能会 显著增加导出时间。

写入文件

默认情况下，export 命令写入 stdout。您也可以使用 -o 选项将内容写入文件

gazou export > my_tweets_file.csv
# is equivalent to
gazou export -o my_tweets_file.csv

虽然如果您中断导出并需要分多批次完成，则只有 -o 选项与 --resume 选项一起使用才能工作。

查询特定关键词

导出所有在 text 字段中包含 "medialab" 的推文

gazou export medialab

搜索引擎不区分大小写，并且会转义 # 或 @：gazou export sciencespo 将导出包含 "@sciencespo" 或 "#SciencesPo" 的推文。然而，它 对重音符号是敏感的：gazou export medialab 不会返回包含 "médialab" 的推文。

使用 Lucene 查询语法，通过 --lucene 选项来编写更复杂的查询。

  • 使用 AND / OR
    gazou export --lucene '(medialab OR médialab) AND ("Sciences Po" OR sciencespo)'

（请注意，即使没有使用 --lucene 选项，包含 AND 或 OR 的查询也将被视为 Lucene 风格）

  • 查询推文以外的其他字段
    gazou export --lucene user_location:paris
  • 查询包含非空字段的推文
    gazou export --lucene place_country_code:*
  • 查询包含空字段的推文
    gazou export --lucene 'NOT retweeted_id:*'
# (this is equivalent to:)
gazou export --exclude-retweets
  • 注意，单引号不会匹配精确短语
    gazou export --lucene "NewYork OR \"New York\"" #match tweets containing "New York" or "NewYork"
gazou export --lucene "NewYork OR 'New York'" #match tweets containing "New" or "York" or "NewYork"

其他可用选项

# Get documentation for all options of gazou export (-h or --help)
gazou export -h

# By default, the export will show a progressbar, which you can disable like this:
gazou export --quiet

# Export a csv of all tweets between 2 dates or datetimes (--since is inclusive and --until exclusive):
gazou export --since 2021-03-24 --until 2021-03-25
# or
gazou export --since 2021-03-24T12:00:00 --until 2021-03-24T13:00:00

# List all available fields for each tweet:
gazou export --list-fields

# Export only a selection of fields (-c / --columns or -s / --select the xsv way):
gazou export -c id,user_screen_name,local_time,links
# or for example to export only the text of the tweets:
gazou export --select text

# Exclude tweets collected via conversations or quotes (i.e. which do not match the keywords defined in config.json)
gazou export --exclude-threads

# Exclude retweets from the export
gazou export --exclude-retweets

# Export all tweets matching a specific ElasticSearch term query, for instance by user name:
gazou export '{"user_screen_name": "medialab_ScPo"}'

# Take a csv file with an "id" column and export only the tweets whose ids are included in this file:
gazou export --export-tweets-from-file list_of_ids.csv

# You can of course combine all of these options, for instance:
gazou export medialab --since 2021-03-24 --until 2021-03-25 -c text --exclude-threads --exclude-retweets -o medialab_tweets_210324_no_threads_no_rts.csv

统计收集的推文数量

Gazouilloire 查询系统也适用于 count 命令。例如，您可以统计推文的转发数量。

gazou count --lucene retweeted_id:*

您还可以使用 --step 参数来按秒/分钟/小时/天/月/年来统计推文数量。

gazou count medialab --step months --since 2018-01-01 --until 2022-01-01

结果将以 CSV 格式输出。

直接使用 ElasticSearch 导出/导入数据

为了运行和重新导入备份，您还可以通过直接与 ElasticSearch 对话，使用构建生态系统中的一些工具来导出或导入数据。

我们建议使用 elasticdump，它需要安装 NodeJs。

# Install the package
npm install -g elasticdump

然后您可以直接使用它，或通过我们内置的脚本 elasticdump.sh 来运行简单的 gazouilloire 集合索引的导出/导入。

gazou scripts elasticdump.sh
# and to read its documentation:
gazou scripts --info elasticdump.sh

高级参数

可以使用许多高级设置来更好地筛选收集的推文并完善语料库。它们都可以在 config.json 文件中修改。

- 关键词

关键词语法遵循 Twitter 搜索引擎的规则。您可以通过在 网站的搜索栏 中输入它们来构建查询。您可以输入单个单词，也可以输入由空格分隔的单词组合（这将查询匹配所有这些单词的推文）。您还可以编写复杂的布尔查询，例如 (medialab OR (media lab)) (Sciences Po OR SciencesPo)，但请注意，只有搜索 API 将用于这些查询，而不是流 API，因此结果可能不那么全面。

一些高级过滤器可以与关键词结合使用，例如 -undesiredkeyword、filter:links、-filter:media、-filter:retweets 等。有关详细信息，请参阅 Twitter API 文档。包含这些查询的查询也仅将在搜索 API 上运行，而不是在流 API 上。

当将 Twitter 用户添加为关键词时，例如 "@medialab_ScPo"，Gazouilloire 将专门查询 "from:medialab_Scpo OR to:medialab_ScPo OR @medialab_ScPo"，以便收集提到该用户的全部推文。

在关键词中使用大写或小写字母不会产生任何影响。

您可以在查询中留下重音符号，因为 Twitter 将自动通过搜索 API 返回带有和不带有重音符号的推文，例如，搜索 "héros" 将找到包含 "heros" 和 "héros" 的推文。流 API 将仅返回精确结果，但它主要补充搜索结果。

关于标签，请注意，查询一个没有 # 字符的单词将返回包含常规单词和带有标签的推文。在关键词内部添加带有 # 字符的标签将仅收集带有标签的推文。

请注意，有三种方法可以进一步筛选

- 语言

为了收集只使用特定语言编写的推文：只需将 "language": "fr" 添加到配置（语言应使用 ISO 639-1 代码）。

- 地理位置信息

只需将配置中添加 "geolocation": "Paris, France" 字段，指定所需的地理边界，或输入所需的框的坐标（例如 [48.70908786918211, 2.1533203125, 49.00274483644453, 2.610626220703125]）

- time_limited_keywords

为了在计划的时间段内过滤特定的关键词，例如

"time_limited_keywords": {
      "#fosdem": [
          ["2021-01-27 04:30", "2021-01-28 23:30"]
      ]
  }

- url_pieces

为了搜索特定网站的部分，可以在该字段中输入URL片段作为关键词。例如

"url_pieces": [
    "medialab.sciencespo.fr",
    "github.com/medialab"
]

- resolve_redirected_links

设置为 true 或 false 以启用或禁用自动解析在推文中找到的所有链接（t.co 链接总是被处理，但这也允许解析所有其他缩短器，如 bit.ly）。

resolving_delay（默认设置为 30）定义了在将错误返回的 URL 保留为原样之前，将重试多少天。

- grab_conversations

设置为 true 以激活在收集到的推文所回答的所有推文语料库中的自动递归检索（警告：在处理数据时应考虑这些内容的存在，这通常会导致收集到不包含查询关键词或远超出收集时间段的推文）。

- catchup_past_week

Twitter 的免费 API 允许收集过去 7 天的推文，这是 gazouilloire 在启动新语料库时默认执行的。将此选项设置为 false 以禁用此功能，并且只收集在收集启动后发布的推文。

- download_media

配置此选项以激活在 media_directory 中自动下载用户在收集到的推文中发布的照片和/或视频（这不包括来自社交媒体卡的图像）。例如以下配置将仅收集图片，不包含视频或 gif

"download_media": {
    "photo": true,
    "video": false,
    "animated_gif": false,
    "media_directory": "path/to/media/directory"
}

所有字段也可以设置为 true 以下载所有内容。media_directory 是 Gazouilloire 存储图像和视频的文件夹。它可以是绝对路径（"/home/user/gazouilloire/my_collection/my_images"），或相对于配置.json 所在目录的路径（"my_images"）。

- timezone

调整推文时间戳应计算的时区。允许的值在 Gazouilloire 启动时设置无效时提出。

- verbose

当设置为 true 时，日志将更详细地记录 Gazouilloire 与 Twitter API 的交互。

守护进程模式

对于生产使用和长期数据收集，Gazouilloire 可以作为守护进程运行（这意味着它在后台执行，并且可以安全地关闭启动它的窗口）。

  • 使用以下命令以守护进程模式启动收集

    gazou start

  • 使用以下命令停止守护进程

    gazou stop

  • 使用以下命令重新启动守护进程

    gazou restart

  • 使用以下命令访问当前收集状态（正在运行/未运行，收集到的推文数量，磁盘使用情况等）

    gazou status

  • Gazouilloire 应该在出现暂时性互联网连接中断时自动重新启动，但它可能会因各种原因（例如 ElasticSearch 崩溃）而偶尔失败。为了确保长期收集持续运行而无需始终检查，我们建议至少每周使用 cronjob 重新启动 Gazouilloire 一次（缺失的推文将在崩溃后 7 天内完成）。为此，提供了一个restart.sh 脚本，该脚本在必要时处理重新启动 ElasticSearch。您可以通过在语料库目录中执行以下操作来安装它

    gazou scripts restart.sh

    脚本顶部提供用例和 cronjob 示例作为注释。您也可以通过执行以下操作来咨询它们

    gazou scripts --info restart.sh

  • 提供了一个示例脚本 daily_mail_export.sh 用于执行每日推文导出并通过电子邮件获取它们。请随意重用并根据您的需求进行调整。

    gazou scripts daily_mail_export.sh
# and to read its documentation:
gazou scripts --info daily_mail_export.sh

  • 还有更多类似的实用脚本可供各种场景使用。

    # You can list them all using --list or -l:
gazou scripts --list
# Read each script's documentation with --info or -i (for instance for "backup_corpus_ids.sh"):
gazou scripts --info backup_corpus_ids.sh
# And install it in the current directory with:
gazou scripts backup_corpus_ids.sh
# Or within a specific different directory using --path or -p:
gazou scripts backup_corpus_ids.sh -p PATH_TO_MY_GAZOUILLOIRE_COLLECTION_DIRECTORY
# Or even install all scripts at once using --all or -a (--path applicable as well)
gazou scripts --all

重置

  • Gazouilloire 将其当前搜索状态存储在收藏夹目录中。这意味着如果您在相同目录中重新启动 Gazouilloire，它将不会再次搜索已收集的推文。如果您想从头开始，可以使用以下方法重置搜索状态以及所有已保存到磁盘上的内容：

    gazou reset

  • 您也可以选择仅删除某些元素，例如存储在 ElasticSearch 中的推文和媒体文件。

    gazou reset --only tweets,media

    --only 参数的可能值：tweets、links、logs、piles、search_state、media

开发

要安装 Gazouilloire 的最新开发版本或帮助开发它，请克隆存储库，并使用 setup.py 文件安装本地版本。

git clone https://github.com/medialab/gazouilloire
cd gazouilloire
python setup.py install

Gazouilloire 的主要代码依赖于 gazouilloire/run.py，其中协调整个多进程架构。下面是所有进程和队列的图示。

  • searcher 通过查询 Twitter 的搜索 API v1.1 按顺序收集所有关键字推文，直到 API 速率允许的范围。
  • streamer 使用 Twitter 的流式 API v1.1 收集实时推文，并从作为关键字关注的使用者那里获取已删除推文的信息。
  • depiler 使用 twitwi 处理和重新格式化推文和已删除推文，然后在 ElasticSearch 中进行索引。它还会提取媒体 URL 和父推文以供 downloader 和 catchupper 使用。
  • downloader 请求所有媒体 URL 并将它们存储在文件系统上（如果启用了 download_media 选项）。
  • catchupper 通过 Twitter 的查找 API v1.1 递归地收集所有收集到的推文的父推文，并将其反馈给 depiler（如果启用了 grab_conversations 选项）。
  • resolver 对收集到的推文中发现的链接运行多线程查询，并尝试使用 minet 解析它们以获得未缩短和统一的 URL（如果启用了 resolve_redirected_links 选项）。

所有三个队列都备份到文件系统中的 pile_***.json 文件中，以便在 Gazouilloire 关闭后重启时重新加载。

multiprocesses

故障排除

ElasticSearch

  • 记得在转移到生产环境时设置堆大小（默认为 1GB）。对于 15-20 百万条推文以下的索引，1GB 是足够的，但对于更重的语料库，请确保设置更高的值。

    在此处设置这些值 /etc/elasticsearch/jvm.options（如果您使用 ElasticSearch 作为服务）或在此处 your_installation_folder/config/jvm.options（如果您有自定义安装文件夹）。

    -Xms2g
-Xmx2g

    在此，堆大小设置为 2GB（如果您需要 5GB，请将值设置为 -Xms5g -Xmx5g 等）。

  • 如果您遇到以下 ElasticSearch 错误消息：max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144]

    :arrow_right: 增加值 max_map_count

    sudo sysctl -w vm.max_map_count=262144

    (来源)

  • 如果在启动 ElasticSearch 时遇到 ClusterBlockException [SERVICE_UNAVAILABLE/1/state not recovered / initialized]

    :arrow_right: 检查 /etc/elasticsearch/elasticsearch.yml 中 gateway.recover_after_nodes 的值

    sudo [YOUR TEXT EDITOR] /etc/elasticsearch/elasticsearch.yml

    将 gateway.recover_after_nodes 的值编辑为与您的节点数匹配（通常为 1 - 可以轻松在此处检查：http://host:port/_nodes）。

出版物

Gazouilloire 演示文稿

使用Gazouilloire的出版物

讨论Gazouilloire的出版物

致谢 & 许可证

Benjamin Ooghe-Tabanou, Béatrice Mazoyer, Jules Farjas & al @ Sciences Po médialab

在Jules' report中了解更多关于Gazouilloire从Python2 & Mongo迁移到Python3 & ElasticSearch的信息。

在médialab tools上发现更多我们的项目。

本工作得到了DIME-Web的支持，它是DIME-SHS研究设备的一部分，由EQUIPEX计划（ANR-10-EQPX-19-01）资助。

Gazouilloire是在GPL 3.0许可证下发布的免费开源软件。

项目详情

验证详情

这些详情已由PyPI 验证
维护者
来自gravatar.com的bmaz头像 bmaz 来自gravatar.com的boogheta头像 boogheta

未验证详情

这些详情尚未由PyPI 验证
项目链接
元数据
  • 许可证： GPL-3.0
  • 作者： Benjamin Ooghe-Tabanou
  • 标签 twitter
  • 要求： Python >=3.7

发布历史 发布通知 | RSS feed

此版本

1.5.0

1.4.0

1.3.0

1.2.3

1.2.2

1.2.1

1.2.0

1.1.1

1.1.0

1.0.2

1.0.1

1.0.0

1.0.0a13 预发布

1.0.0a12 预发布

1.0.0a11 预发布

1.0.0a10 预发布

1.0.0a9 预发布

1.0.0a8 预发布

1.0.0a7 预发布

1.0.0a6 预发布

1.0.0a5 预发布

1.0.0a4 预发布

1.0.0a3 预发布

1.0.0a2 预发布

1.0.0a1 预发布

1.0.0a0 预发布

下载文件

下载适用于您平台的文件。如果您不确定选择哪一个，请了解有关安装包的更多信息。

源代码分发

gazouilloire-1.5.0.tar.gz (81.2 kB 查看哈希值)

上传时间 源代码

构建分发

gazouilloire-1.5.0-py3-none-any.whl (82.5 kB 查看哈希值)

上传时间 Python 3

由

AWS AWS 云计算和安全赞助商 Datadog Datadog 监控 Fastly Fastly CDN Google Google 下载分析 Microsoft Microsoft PSF 赞助商 Pingdom Pingdom 监控 Sentry Sentry 错误日志 StatusPage StatusPage 状态页面