Feed 导出

在实现爬虫时最常需要的功能之一是能够正确存储抓取到的数据，而这通常意味着生成一个包含抓取数据的“导出文件”（通常称为“导出 feed”），以供其他系统使用。

Scrapy 通过 Feed 导出开箱即用地提供了此功能，它允许您使用多种序列化格式和存储后端生成包含抓取项目的 feed。

本页提供了所有 feed 导出功能的详细文档。如果您正在寻找分步指南，请查阅 Zyte 的导出指南。

序列化格式

为了序列化抓取到的数据，feed 导出使用 Item 导出器。这些格式开箱即用：

JSON
JSON 行
CSV
XML

但您也可以通过 FEED_EXPORTERS 设置扩展支持的格式。

JSON

FEEDS 设置中 format 键的值：json
使用的导出器：JsonItemExporter
如果您将 JSON 用于大型 feed，请参阅此警告。

JSON 行

FEEDS 设置中 format 键的值：jsonlines
使用的导出器：JsonLinesItemExporter

CSV

FEEDS 设置中 format 键的值：csv
使用的导出器：CsvItemExporter
要指定要导出的列、它们的顺序和列名，请使用 FEED_EXPORT_FIELDS。其他 feed 导出器也可以使用此选项，但对于 CSV 来说它很重要，因为与许多其他导出格式不同，CSV 使用固定标题。

XML

FEEDS 设置中 format 键的值：xml
使用的导出器：XmlItemExporter

Pickle

FEEDS 设置中 format 键的值：pickle
使用的导出器：PickleItemExporter

Marshal

FEEDS 设置中 format 键的值：marshal
使用的导出器：MarshalItemExporter

存储后端

使用 feed 导出时，您可以通过一个或多个 URI（通过 FEEDS 设置）定义 feed 的存储位置。feed 导出支持多种存储后端类型，这些类型由 URI 方案定义。

开箱即用的存储后端包括：

本地文件系统
FTP
S3 (需要 boto3)
Google Cloud Storage (GCS) (需要 google-cloud-storage)
标准输出

如果所需的外部库不可用，某些存储后端可能无法使用。例如，S3 后端仅在安装了 boto3 库时才可用。

存储 URI 参数

存储 URI 还可以包含在创建 feed 时会被替换的参数。这些参数是：

%(time)s - 在创建 feed 时被替换为时间戳
%(name)s - 被替换为 spider 名称

任何其他命名参数都将被同名的 spider 属性替换。例如，%(site_id)s 会在创建 feed 时被替换为 spider.site_id 属性。

以下是一些示例说明：

在 FTP 中为每个 spider 使用一个目录进行存储
- ftp://user:password@ftp.example.com/scraping/feeds/%(name)s/%(time)s.json
在 S3 中为每个 spider 使用一个目录进行存储
- s3://mybucket/scraping/feeds/%(name)s/%(time)s.json

注意

Spider 参数成为 spider 属性，因此它们也可以用作存储 URI 参数。

存储后端

本地文件系统

feed 存储在本地文件系统中。

URI 方案：file
示例 URI：file:///tmp/export.csv
所需外部库：无

请注意，对于本地文件系统存储（仅限），如果指定绝对路径，例如 /tmp/export.csv（仅限 Unix 系统），则可以省略方案。或者，您也可以使用 pathlib.Path 对象。

FTP

feed 存储在 FTP 服务器中。

URI 方案：ftp
示例 URI：ftp://user:pass@ftp.example.com/path/to/export.csv
所需外部库：无

FTP 支持两种不同的连接模式：主动或被动。Scrapy 默认使用被动连接模式。要改用主动连接模式，请将 FEED_STORAGE_FTP_ACTIVE 设置为 True。

此存储后端在 FEEDS 中 overwrite 键的默认值为：True。

注意

overwrite 中的 True 值将导致您丢失数据的先前版本。

此存储后端使用延迟文件交付。

S3

feed 存储在 Amazon S3 上。

URI 方案：s3
示例 URI
- s3://mybucket/path/to/export.csv
- s3://aws_key:aws_secret@mybucket/path/to/export.csv
所需外部库：boto3 >= 1.20.0

AWS 凭据可以作为用户名/密码在 URI 中传递，或者通过以下设置传递：

您还可以使用以下设置定义导出 feed 的自定义 ACL、自定义端点和区域名称：

此存储后端在 FEEDS 中 overwrite 键的默认值为：True。

注意

overwrite 中的 True 值将导致您丢失数据的先前版本。

此存储后端使用延迟文件交付。

Google Cloud Storage (GCS)

feed 存储在 Google Cloud Storage 上。

URI 方案：gs
示例 URI
- gs://mybucket/path/to/export.csv
所需外部库：google-cloud-storage。

有关身份验证的更多信息，请参阅 Google Cloud 文档。

您可以通过以下设置设置 项目 ID 和 访问控制列表 (ACL)：

此存储后端在 FEEDS 中 overwrite 键的默认值为：True。

注意

overwrite 中的 True 值将导致您丢失数据的先前版本。

此存储后端使用延迟文件交付。

标准输出

feed 被写入 Scrapy 进程的标准输出。

URI 方案：stdout
示例 URI：stdout:
所需外部库：无

延迟文件交付

如上所述，一些描述的存储后端使用延迟文件交付。

这些存储后端不会在项目抓取时立即将项目上传到 feed URI。相反，Scrapy 会将项目写入一个临时本地文件，并且只有在所有文件内容都已写入（即在爬取结束时）之后，该文件才会被上传到 feed URI。

如果在使用这些存储后端之一时希望项目交付提前开始，请使用 FEED_EXPORT_BATCH_ITEM_COUNT 将输出项目拆分为多个文件，每个文件具有指定的项目最大数量。这样，一旦文件达到最大项目数量，该文件就会被交付到 feed URI，从而允许项目交付在爬取结束之前很久就开始。

项目过滤

您可以使用 feed 选项中的 item_classes 选项来过滤您希望特定 feed 允许的项目。只有指定类型的项目才会被添加到 feed 中。

item_classes 选项由 ItemFilter 类实现，它是 item_filter feed 选项的默认值。

您可以通过实现 ItemFilter 的 accepts 方法并以 feed_options 作为参数来创建自己的自定义过滤类。

例如

class MyCustomFilter:
    def __init__(self, feed_options):
        self.feed_options = feed_options

    def accepts(self, item):
        if "field1" in item and item["field1"] == "expected_data":
            return True
        return False

您可以将您的自定义过滤类分配给 feed 的 item_filter 选项。请参阅 FEEDS 获取示例。

ItemFilter

class scrapy.extensions.feedexport.ItemFilter(feed_options: dict[str, Any] | None)[source]

FeedExporter 将使用它来决定是否允许将项目导出到特定 feed。

参数:: feed_options (dict) – 从 FeedExporter 传递的特定于 feed 的选项

accepts(item: Any) → bool[source]

如果 item 应该被导出则返回 True，否则返回 False。

参数:: item (Scrapy 项目) – 用户希望检查是否可接受的抓取项目
返回:: 如果接受则为 True，否则为 False
返回类型:: bool

后处理

Scrapy 提供了一个选项来激活插件，以便在 feed 导出到 feed 存储之前对其进行后处理。除了使用内置插件外，您还可以创建自己的插件。

这些插件可以通过 feed 的 postprocessing 选项激活。该选项必须传递一个后处理插件列表，按照您希望 feed 被处理的顺序。这些插件可以声明为导入字符串或插件的导入类。插件的参数可以通过 feed 选项传递。请参阅 feed 选项获取示例。

内置插件

class scrapy.extensions.postprocessing.GzipPlugin(file: BinaryIO, feed_options: dict[str, Any])[source]

使用 gzip 压缩接收到的数据。

接受的 feed_options 参数

gzip_compresslevel
gzip_mtime
gzip_filename

有关参数的更多信息，请参阅 gzip.GzipFile。

class scrapy.extensions.postprocessing.LZMAPlugin(file: BinaryIO, feed_options: dict[str, Any])[source]

使用 lzma 压缩接收到的数据。

接受的 feed_options 参数

lzma_format
lzma_check
lzma_preset
lzma_filters

注意

lzma_filters 不能用于 pypy 7.3.1 及更早版本。

有关参数的更多信息，请参阅 lzma.LZMAFile。

class scrapy.extensions.postprocessing.Bz2Plugin(file: BinaryIO, feed_options: dict[str, Any])[source]

使用 bz2 压缩接收到的数据。

接受的 feed_options 参数

bz2_compresslevel

有关参数的更多信息，请参阅 bz2.BZ2File。

自定义插件

每个插件都是一个必须实现以下方法的类：

__init__(self, file, feed_options)

初始化插件。

参数:

file – 至少实现了 write、tell 和 close 方法的类文件对象
feed_options (dict) – 特定于 feed 的选项

write(self, data): 处理并将 data (bytes 或 memoryview) 写入插件的目标文件。它必须返回写入的字节数。

close(self)

清理插件。

例如，您可能希望关闭一个文件封装器，该封装器可能已用于压缩写入 __init__ 方法中接收到的文件的数据。

警告

不要在 __init__ 方法中关闭文件。

要将参数传递给您的插件，请使用 feed 选项。然后，您可以从插件的 __init__ 方法中访问这些参数。

设置

以下是用于配置 feed 导出的设置：

FEEDS (强制)
FEED_EXPORT_ENCODING
FEED_STORE_EMPTY
FEED_EXPORT_FIELDS
FEED_EXPORT_INDENT
FEED_STORAGES
FEED_STORAGE_FTP_ACTIVE
FEED_STORAGE_S3_ACL
FEED_EXPORTERS
FEED_EXPORT_BATCH_ITEM_COUNT

FEEDS

默认值：{}

一个字典，其中每个键都是一个 feed URI（或一个 pathlib.Path 对象），每个值都是一个包含特定 feed 配置参数的嵌套字典。

此设置是启用 feed 导出功能所必需的。

有关支持的 URI 方案，请参阅存储后端。

例如

{
    'items.json': {
        'format': 'json',
        'encoding': 'utf8',
        'store_empty': False,
        'item_classes': [MyItemClass1, 'myproject.items.MyItemClass2'],
        'fields': None,
        'indent': 4,
        'item_export_kwargs': {
           'export_empty_fields': True,
        },
    },
    '/home/user/documents/items.xml': {
        'format': 'xml',
        'fields': ['name', 'price'],
        'item_filter': MyCustomFilter1,
        'encoding': 'latin1',
        'indent': 8,
    },
    pathlib.Path('items.csv.gz'): {
        'format': 'csv',
        'fields': ['price', 'name'],
        'item_filter': 'myproject.filters.MyCustomFilter2',
        'postprocessing': [MyPlugin1, 'scrapy.extensions.postprocessing.GzipPlugin'],
        'gzip_compresslevel': 5,
    },
}

以下是接受的键及其在未为特定 feed 定义提供该键时用作回退值的设置列表：

format: 序列化格式。

此设置是强制性的，没有回退值。
batch_item_count: 回退到 FEED_EXPORT_BATCH_ITEM_COUNT。
encoding: 回退到 FEED_EXPORT_ENCODING。
fields: 回退到 FEED_EXPORT_FIELDS。
item_classes: 要导出的项目类列表。

如果未定义或为空，则导出所有项目。
item_filter: 用于过滤要导出项目的过滤类。

默认使用 ItemFilter。
indent: 回退到 FEED_EXPORT_INDENT。
item_export_kwargs: 包含对应项目导出器类的关键字参数的 dict。
overwrite: 如果文件已存在，是覆盖文件 (True) 还是追加到其内容 (False)。

默认值取决于存储后端：
- 本地文件系统: False
- FTP: True
  
  注意
  
  某些 FTP 服务器可能不支持追加文件（APPE FTP 命令）。
- S3: True (不支持追加)
- Google Cloud Storage (GCS): True (不支持追加)
- 标准输出: False (不支持覆盖)
store_empty: 回退到 FEED_STORE_EMPTY。
uri_params: 回退到 FEED_URI_PARAMS。
postprocessing: 用于后处理的插件列表。

插件将按照传递列表中的顺序使用。

FEED_EXPORT_ENCODING

默认值："utf-8" (回退: None)

feed 将使用的编码。

如果设置为 None，则除了 JSON 输出外，所有内容都使用 UTF-8，而 JSON 输出出于历史原因使用安全的数字编码（\uXXXX 序列）。

如果您也希望 JSON 使用 UTF-8，请使用 "utf-8"。

FEED_EXPORT_FIELDS

默认值：None

使用 FEED_EXPORT_FIELDS 设置定义要导出的字段、它们的顺序和它们的输出名称。有关更多信息，请参阅 BaseItemExporter.fields_to_export。

FEED_EXPORT_INDENT

默认值：0

每个级别用于缩进输出的空格数量。如果 FEED_EXPORT_INDENT 是一个非负整数，则数组元素和对象成员将以该缩进级别进行美观打印。缩进级别为 0（默认值）或负数，将使每个项目在新行上显示。None 选择最紧凑的表示形式。

目前仅由 JsonItemExporter 和 XmlItemExporter 实现，即当您导出到 .json 或 .xml 时。

FEED_STORE_EMPTY

默认值：True

是否导出空 feed（即没有项目的 feed）。如果为 False，并且没有要导出的项目，则不会创建新文件，也不会修改现有文件，即使启用了覆盖 feed 选项。

FEED_STORAGES

默认值：{}

一个字典，包含您的项目支持的额外 feed 存储后端。键是 URI 方案，值是存储类的路径。

FEED_STORAGE_FTP_ACTIVE

默认值：False

将 feed 导出到 FTP 服务器时是否使用主动连接模式（True）或被动连接模式（False，默认）。

有关 FTP 连接模式的信息，请参阅主动 FTP 和被动 FTP 之间有什么区别？。

FEED_STORAGE_S3_ACL

默认值：'' (空字符串)

一个字符串，包含您的项目导出到 Amazon S3 的 feed 的自定义 ACL。

有关可用值的完整列表，请访问 Amazon S3 文档中的 Canned ACL 部分。

FEED_STORAGES_BASE

默认值

{
    "": "scrapy.extensions.feedexport.FileFeedStorage",
    "file": "scrapy.extensions.feedexport.FileFeedStorage",
    "stdout": "scrapy.extensions.feedexport.StdoutFeedStorage",
    "s3": "scrapy.extensions.feedexport.S3FeedStorage",
    "ftp": "scrapy.extensions.feedexport.FTPFeedStorage",
}

一个字典，包含 Scrapy 支持的内置 feed 存储后端。您可以通过在 FEED_STORAGES 中将其 URI 方案设置为 None 来禁用任何这些后端。例如，要禁用内置的 FTP 存储后端（不替换），请将其放入您的 settings.py 中：

FEED_STORAGES = {
    "ftp": None,
}

FEED_EXPORTERS

默认值：{}

一个字典，包含您的项目支持的额外导出器。键是序列化格式，值是 Item 导出器类的路径。

FEED_EXPORTERS_BASE

默认值

{
    "json": "scrapy.exporters.JsonItemExporter",
    "jsonlines": "scrapy.exporters.JsonLinesItemExporter",
    "jsonl": "scrapy.exporters.JsonLinesItemExporter",
    "jl": "scrapy.exporters.JsonLinesItemExporter",
    "csv": "scrapy.exporters.CsvItemExporter",
    "xml": "scrapy.exporters.XmlItemExporter",
    "marshal": "scrapy.exporters.MarshalItemExporter",
    "pickle": "scrapy.exporters.PickleItemExporter",
}

一个字典，包含 Scrapy 支持的内置 feed 导出器。您可以通过在 FEED_EXPORTERS 中将其序列化格式设置为 None 来禁用任何这些导出器。例如，要禁用内置的 CSV 导出器（不替换），请将其放入您的 settings.py 中：

FEED_EXPORTERS = {
    "csv": None,
}

FEED_EXPORT_BATCH_ITEM_COUNT

默认值：0

如果赋值一个大于 0 的整数，Scrapy 将生成多个输出文件，每个输出文件最多存储指定数量的项目。

生成多个输出文件时，您必须在 feed URI 中使用以下至少一个占位符来指示如何生成不同的输出文件名：

%(batch_time)s - 在创建 feed 时被替换为时间戳（例如 2020-03-28T14-45-08.237134）
%(batch_id)d - 被替换为批次的基于 1 的序列号。

使用 printf 风格的字符串格式化来改变数字格式。例如，要通过根据需要引入前导零使批次 ID 成为 5 位数字，请使用 %(batch_id)05d（例如，3 变为 00003，123 变为 00123）。

例如，如果您的设置包含：

FEED_EXPORT_BATCH_ITEM_COUNT = 100

并且您的 crawl 命令行是：

scrapy crawl spidername -o "dirname/%(batch_id)d-filename%(batch_time)s.json"

上述命令行可以生成类似以下的目录树：

->projectname
-->dirname
--->1-filename2020-03-28T14-45-08.237134.json
--->2-filename2020-03-28T14-45-09.148903.json
--->3-filename2020-03-28T14-45-10.046092.json

其中第一个和第二个文件都包含正好 100 个项目。最后一个文件包含 100 个或更少的项目。

FEED_URI_PARAMS

默认值：None

一个字符串，包含一个函数的导入路径，该函数用于设置要通过 printf 风格的字符串格式化应用于 feed URI 的参数。

函数签名应如下所示：

scrapy.extensions.feedexport.uri_params(params, spider)

返回一个 dict 包含键值对，用于使用 printf 风格的字符串格式化应用于 feed URI。

参数:

params (dict) –
默认键值对

具体而言：
- batch_id: 文件批次 ID。请参阅 FEED_EXPORT_BATCH_ITEM_COUNT。
  
  如果 FEED_EXPORT_BATCH_ITEM_COUNT 为 0，则 batch_id 始终为 1。
- batch_time: UTC 日期和时间，采用 ISO 格式，其中 : 替换为 -。
  
  请参阅 FEED_EXPORT_BATCH_ITEM_COUNT。
- time: batch_time，微秒设置为 0。
spider (scrapy.Spider) – feed 项目的源 spider

注意

函数应该返回一个新的字典，就地修改接收到的 params 已被弃用。

例如，要在 feed URI 中包含源 spider 的 name：

在您的项目中的某个位置定义以下函数：

# myproject/utils.py
def uri_params(params, spider):
    return {**params, "spider_name": spider.name}

在您的设置中将 FEED_URI_PARAMS 指向该函数：

# myproject/settings.py
FEED_URI_PARAMS = "myproject.utils.uri_params"

在您的 feed URI 中使用 %(spider_name)s：

scrapy crawl <spider_name> -o "%(spider_name)s.jsonl"