从 Web-API 加载数据

支持的协议包括 file、http、https、s3、gs、hdfs，并允许重定向。

如果未提供协议，此过程将尝试检查该 URL 是否为文件。

如果启用了 apoc.import.file.use_neo4j_config，则这些过程将通过读取配置参数 dbms.security.allow_csv_import_from_file_urls 和 server.directories.import 来检查是否允许文件系统访问，并可能将其限制在特定目录中。如果您想移除这些限制，请设置 apoc.import.file.use_neo4j_config=false。

过程描述

过程	描述
`apoc.load.json(urlOrKeyOrBinary ANY, path STRING, config MAP<STRING, ANY>)`	从 URL 加载 JSON
`apoc.load.xml(urlOrBinary ANY, path STRING, config MAP<STRING, ANY>, simple BOOLEAN)`	从 URL 加载 XML

apoc.load.json(urlOrKeyOrBinary ANY, path STRING, config MAP<STRING, ANY>)

从 URL 加载 JSON

apoc.load.xml(urlOrBinary ANY, path STRING, config MAP<STRING, ANY>, simple BOOLEAN)

从 URL 加载 XML

在使用上表中的任何过程时，在配置映射中添加 failOnError:false（默认为 true）将使它们在出错时不会失败。相反，该过程将返回零行。例如：

CALL apoc.load.json('http://example.com/test.json', null, {failOnError:false})

从压缩文件 (zip/tar/tar.gz/tgz) 加载

加载压缩文件时，必须在配置选项中提供压缩算法。例如，在以下情况下，如果 xmlCompressed 是一个 .gzip 后缀的文件，则需要向过程调用提供配置选项 {compression: 'GZIP'}，以便将文档的根节点 / 加载到内存中的 Cypher 映射中。

CALL apoc.load.xml(xmlCompressed, '/', {compression: 'GZIP'})

有关其他有效压缩配置值的详细信息，请参阅 apoc.load.xml 文档。

默认情况下，解压后的文件大小限制为其压缩大小的 200 倍。该数值可以通过调整 apoc.conf 中的配置选项 apoc.max.decompression.ratio 来更改（不能设为 0，因为这会使解压无法进行）。如果提供负数，则解压大小将不受限制。这会使数据库暴露在潜在的“zip 炸弹”攻击之下。

尝试加载超过相对于原始压缩文件比例限制的未压缩文件时，将产生以下消息：

The file dimension exceeded maximum size in bytes, 250000, which is 250 times the width of the original file.
The InputStream has been blocked because the file could be a compression bomb attack.

从压缩文件 (zip/tar/tar.gz/tgz) 加载单个文件

从压缩文件加载数据时，我们需要在压缩文件中的文件名或路径前添加 ! 字符。例如：

加载压缩的 JSON 文件

CALL apoc.load.json("https://github.com/neo4j/apoc/blob/2026.03/core/src/test/resources/testload.tgz?raw=true!person.json");

使用 S3、GCS 或 HDFS 协议

要使用这些协议中的任何一个，需要下载额外的依赖 jar 包并将其复制到插件目录 <NEO4J_HOME>/plugins 中，具体如下：

表 1. AWS 依赖 jar (S3)
AWS 依赖 jar	APOC 版本
apoc-aws-dependencies-5.16.jar	5.16
apoc-aws-dependencies-5.15.jar	5.15
apoc-aws-dependencies-5.14.jar	5.14
apoc-aws-dependencies-5.13.jar	5.13
apoc-aws-dependencies-5.12.jar	5.12
apoc-aws-dependencies-5.11.jar	5.11
apoc-aws-dependencies-5.10.jar	5.10

表 2. GCS 依赖 jar
GCS 依赖 jar	APOC 版本
apoc-gcs-dependencies-5.16.jar	5.16
apoc-gcs-dependencies-5.15.jar	5.15
apoc-gcs-dependencies-5.14.jar	5.14
apoc-gcs-dependencies-5.13.jar	5.13
apoc-gcs-dependencies-5.12.jar	5.12
apoc-gcs-dependencies-5.11.jar	5.11
apoc-gcs-dependencies-5.10.jar	5.10

表 3. HDFS 依赖 jar
HDFS 依赖 jar	APOC 版本
apoc-hadoop-dependencies-5.16.jar	5.16
apoc-hadoop-dependencies-5.15.jar	5.15
apoc-hadoop-dependencies-5.14.jar	5.14
apoc-hadoop-dependencies-5.13.jar	5.13
apoc-hadoop-dependencies-5.12.jar	5.12
apoc-hadoop-dependencies-5.11.jar	5.11
apoc-hadoop-dependencies-5.10.jar	5.10

这些依赖 jar 由 APOC Extended 库维护。Neo4j 不支持此库。

将 jar 复制到插件目录后，需要重新启动数据库。

使用 S3 协议

S3 URL 必须采用以下格式：

s3://accessKey:secretKey[:sessionToken]@endpoint:port/bucket/key（其中 sessionToken 是可选的），或者
s3://endpoint:port/bucket/key?accessKey=accessKey&secretKey=secretKey[&sessionToken=sessionToken]（其中 sessionToken 是可选的），或者
s3://endpoint:port/bucket/key（如果 accessKey、secretKey 和可选的 sessionToken 已在环境变量中提供）

使用 Google Cloud Storage

Google Cloud Storage URL 具有以下形式：

gs://<bucket_name>/<file_path>

可以通过额外的 authenticationType 查询参数指定授权类型：

NONE：用于公共存储桶（如果未指定参数，则这是默认行为）
GCP_ENVIRONMENT：当 Neo4j 在 Google Cloud 中运行时，作为服务帐户进行被动身份验证
PRIVATE_KEY：用于使用为服务帐户生成的私钥（需要按照 Google 官方文档的说明，设置指向私钥 JSON 文件的 GOOGLE_APPLICATION_CREDENTIALS 环境变量。）

示例

gs://bucket/test-file.csv?authenticationType=GCP_ENVIRONMENT