Shopify

可用性

核心 标准 Plus Pro Enterprise Flex 自托管 Enterprise PyAirbyte

支持级别

Airbyte

连接器版本

3.1.2 (上次更新 8 天前)

CDK 版本

6.61.6

同步成功率

使用率

定义 ID

9da77001-af33-4bcd-be46-6252bf9342b9

此页面包含 Shopify 来源连接器的设置指南和参考信息。

先决条件

• 一个活跃的 Shopify 商店。
• 如果您正在同步来自您不拥有的商店的数据，您需要 请求访问您客户的商店（帐户所有者不需要）。

• 对于 Airbyte 开源 用户：具有启用 read_ 范围的自定义 Shopify 应用程序。

设置指南

此连接器支持 OAuth2.0 和 API 密码（用于私有应用程序）身份验证方法。

设置 Shopify

注意

对于现有的 Airbyte Cloud 客户，如果您当前正在使用 API 密码 身份验证方法，请切换到 OAuth2.0，因为 API 密码很快将被弃用。此更改不会影响 Airbyte 开源 连接。

对于 Airbyte Cloud：

1. 登录到您的 Airbyte Cloud 账户。
2. 点击“来源”，然后点击“+ 新来源”。
3. 在设置来源页面上，从来源类型下拉菜单中选择 Shopify。
4. 输入 Shopify 连接器的名称。

使用 OAuth2.0 连接

1. 选择一个 来源名称。
2. 点击 验证您的 Shopify 帐户。
3. 点击 安装应用 以安装 Airbyte 应用程序。如果您尚未登录，请登录您的帐户。选择您要同步的商店并查看同意表单。点击 安装应用 以完成安装。

4. 在您验证 Shopify 帐户后，Shopify 商店 字段将根据您选择的商店自动填写。填写后，请确认该值准确无误。

5. (可选) 您可以设置 复制开始日期 作为数据复制的起始点。在此日期之前创建的任何数据都不会被同步。默认值为 2020 年 1 月 1 日。

6. 点击 设置来源 并等待连接测试完成。

对于 Airbyte 开源：

1. 导航到 Airbyte 开源仪表板。
2. 点击“来源”，然后点击“+ 新来源”。
3. 在设置来源页面上，从来源类型下拉菜单中选择 Shopify。
4. 输入 Shopify 连接器的名称。

创建自定义应用

要通过 API 验证 Shopify，需要一个 自定义应用程序。请按照以下说明创建自定义应用程序并找到您的 Admin API 访问令牌。

1. 登录您的 Shopify 帐户。
2. 在仪表板中，导航到 设置 > 应用和销售渠道 > 开发应用 > 创建应用。
3. 为您的新应用选择一个名称。
4. 选择 配置 Admin API 范围。
5. 授予以下范围列表的访问权限。仅选择以 read_ 开头的范围，而不是 write_（例如 read_locations、read_price_rules 等）。
6. 点击 安装应用 以授予此应用访问您数据的权限。
7. 安装完成后，转到 API 凭据 以复制 Admin API 访问令牌。现在您可以设置 Airbyte 中的来源了！

使用 API 密码连接

1. 输入一个 来源名称。
2. 输入您的 Shopify 商店 名称。您可以在登录 Shopify 时或在设置的商店详细信息部分找到它。
3. 对于 API 密码，输入您的自定义应用程序的 Admin API 访问令牌。
4. (可选) 您可以设置 复制开始日期 作为数据复制的起始点。在此日期之前创建的任何数据都不会被同步。请注意，默认值为 2020 年 1 月 1 日。
5. 点击 设置来源 并等待连接测试完成。

自定义应用范围

将以下范围添加到您的自定义应用程序，以确保 Airbyte 可以同步所有可用数据。有关访问范围的更多信息，请参阅 Shopify 文档。

• read_analytics
• read_assigned_fulfillment_orders
• read_content
• read_customers
• read_discounts
• read_draft_orders
• read_fulfillments
• read_gdpr_data_request
• read_gift_cards
• read_inventory
• read_legal_policies
• read_locations
• read_locales
• read_marketing_events
• read_merchant_managed_fulfillment_orders
• read_online_store_pages
• read_order_edits
• read_orders
• read_price_rules
• read_product_listings
• read_products
• read_publications
• read_reports
• read_resource_feedbacks
• read_script_tags
• read_shipping
• read_shopify_payments_accounts
• read_shopify_payments_bank_accounts
• read_shopify_payments_disputes
• read_shopify_payments_payouts
• read_themes
• read_third_party_fulfillment_orders
• read_translations

支持的同步模式

Shopify 来源连接器支持以下 同步模式

功能	支持？
完全刷新同步	是
增量同步	是

Shopify 来源支持完全刷新和增量同步。您可以选择此连接器是仅复制新的或更新的数据，还是每次运行同步时复制表格和列中所有行。

此来源可以同步 Shopify REST API 和 Shopify GraphQL API 和 Shopify GraphQL BULK API 的数据

支持的流

• 已放弃的结账
• 文章
• 余额交易
• 博客
• 收集
• 系列（GraphQL）
• 国家/地区（GraphQL）
• 自定义系列
• 客户
• 客户旅程摘要（GraphQL）
• 客户地址（GraphQL）
• 草稿订单
• 折扣代码（GraphQL）
• 争议
• 履行
• 履行订单（GraphQL）
• 库存项目（GraphQL）
• 库存水平（GraphQL）
• 位置
• 元字段（GraphQL）
• 订单协议（GraphQL）
• 订单
• 订单退款
• 订单风险（GraphQL）
• 页面
• 价格规则
• 产品（GraphQL）
• 已删除的产品（GraphQL） - 产品删除事件
• 产品图片（GraphQL）
• 产品变体（GraphQL）
• 商店
• 智能系列
• 交易
• 交易（GraphQL）
• 投标交易

实体关系图 (ERD)

捕获已删除的记录

该连接器捕获 Articles、Blogs、CustomCollections、Orders、Pages 和 PriceRules 流中的记录删除。当记录被删除时，连接器会输出一个包含该记录的 ID 以及填充了 deleted_at、deleted_message 和 deleted_description 字段的记录。已删除记录的其他字段均未填充。

对于已删除的产品，请使用专用的 Deleted Products 流，该流查询 Shopify GraphQL Events API 以获取产品删除事件。此流返回包含 id（产品 ID）、deleted_at、deleted_message 和 shop_url 字段的记录。

请查看以下 Shopify 文档，了解有关检索已删除记录的更多信息。

营销归因数据

与 营销归因相关的数据可以在几个不同的流中找到。同步这些流以了解营销效果

• Customer Journey Summary (firstVisit.source, firstVisit.sourcetype)
• Orders (referring_site, source_name)
• Abandoned Checkouts (referring_site, source_name)

功能

功能	支持？(是/否)
完全刷新同步	是
增量 - 追加同步	是
命名空间	否

数据类型映射

集成类型	Airbyte 类型
字符串	字符串
数字	数字
array	array
对象	对象
布尔值	布尔值

限制和故障排除

展开以查看 Shopify 连接器限制和故障排除的详细信息

连接器限制

速率限制

Shopify 有一些 速率限制。通常，不应出现节流或超出速率限制的问题，但在某些极端情况下，您可能会遇到以下警告消息

"Caught retryable error '<some_error> or null' after <some_number> tries.
Waiting <some_number> seconds then retrying..."

当连接器遇到 429 - Rate Limit Exceeded HTTP 错误时，这是预期的。在短暂的回退期后，同步操作将继续成功。

对于所有 Shopify GraphQL BULK api 请求，这些限制适用：https://shopify.dev/docs/api/usage/bulk-operations/queries#operation-restrictions。请注意，不同的请求有不同的限制。

故障排除

• 如果您在使用 OAuth2.0 身份验证时遇到访问错误，请确保您已遵循此 Shopify 文章 首先请求访问客户端的商店。一旦授予访问权限，您应该能够继续使用 OAuth2.0 身份验证。
• 如果您收到“由于另一个作业正在运行，因此此时无法创建 BULK 作业。”错误，请 检查您的作业进度 使用 Shopify GraphQL BULK api。
• 如果您需要取消 Shopify GraphQL BULK 作业，请遵循 这些步骤。您需要当前正在进行的作业 ID 才能取消。
• 在我们的 Airbyte 论坛上查看 Shopify 来源连接器的常见故障排除问题 此处。

参考

配置字段参考

字段

类型

属性名称

字符串

shop

整数

bulk_window_in_days

对象

credentials

布尔值

fetch_transactions_user_id

整数

job_checkpoint_interval

布尔值

job_product_variants_include_pres_prices

整数

job_termination_threshold

字符串

start_date

变更日志

展开以查看

版本	日期	拉取请求	主题
3.1.2	2026-01-15	71188	在连接检查中处理 CDK 异常
3.1.1	2026-01-06	71035	修复 countries 流中 profile_location_groups 为空时的 IndexError
3.1.0	2026-01-05	71005	使用 GraphQL Events API 添加 deleted_products 流
3.0.13	2025-10-21	68245	更新依赖项
3.0.12	2025-10-14	67805	更新依赖项
3.0.11	2025-10-07	67448	更新依赖项
3.0.10	2025-09-30	66904	更新依赖项
3.0.9	2025-09-16	66291	将发布候选版本 3.0.9-rc.1 提升到主版本。
3.0.9-rc.1	2025-09-09	65987	使用筛选字段值调整具有 ID 光标字段的流的切片。
3.0.8	2025-09-04	65552	修复 Metafield 子流的增量同步。
3.0.7	2025-06-02	59015	🐙 source-shopify: 更新依赖项 [2025-05-17]
3.0.6	2025-05-28	60797	通过添加动态页面限制修复 orders 和 order_refunds 流中的 500 错误。
3.0.5	2025-04-23	58598	修复 product_variants 流中 Null measurement_weight 字段的 AttributeError
3.0.4	2025-04-19	58431	更新依赖项
3.0.3	2025-04-12	57984	更新依赖项
3.0.2	2025-04-05	57449	更新依赖项
3.0.1	2025-03-29	56861	更新依赖项
3.0.0	2025-03-27	55823	更新 API 版本
2.6.7	2025-03-22	56316	更新依赖项
2.6.6	2025-03-08	55621	更新依赖项
2.6.5	2025-03-01	55126	更新依赖项
2.6.4	2025-02-22	54477	更新依赖项
2.6.3	2025-02-15	51983	更新依赖项
2.6.2	2025-01-14	50976	重试返回 HTTP 500 的请求
2.6.1	2025-02-16	51602	更新了关于 此更改的弃用通知的 UpgradeDeadline
2.6.0	2025-01-15	51037	从流目录中弃用了 ProductsGraphQL 和 CustomerSavedSearch 流
2.5.18	2025-01-11	51326	更新依赖项
2.5.17	2025-01-06	50884	将 moments 字段添加到 Customer Journey Summary 流
2.5.16	2025-01-04	50938	更新依赖项
2.5.15	2024-12-28	50779	更新依赖项
2.5.14	2024-12-21	49088	更新依赖项
2.5.13	2024-12-11	49134	为支持 BULK 的流添加了 checkpointed value 冲突检测
2.5.12	2024-11-25	48661	从这个版本开始，Docker 镜像现在是 rootless。 请注意，此版本和未来的版本将与 Airbyte 版本早于 0.64 不兼容
2.5.11	2024-11-07	48402	将 image_src、image_url，包括 options 添加到 Product Variants 流
2.5.10	2024-11-05	48322	更新依赖项
2.5.9	2024-10-29	47814	更新依赖项
2.5.8	2024-10-28	47044	更新依赖项
2.5.7	2024-10-14	46552	为 BULK 子流添加 parent state 跟踪
2.5.6	2024-10-12	46844	更新依赖项
2.5.5	2024-10-05	46578	引发缺失流的异常
2.5.4	2024-10-05	45759	更新依赖项
2.5.3	2024-09-27	46095	修复了 Product Images、Metafield Product Images 和 Metafield Products 流的增量同步中的重复项
2.5.2	2024-09-17	45633	为 product_variants 流添加 read_inventory 作为必需的作用域
2.5.1	2024-09-14	45255	更新依赖项
2.5.0	2024-09-06	45190	迁移到 CDK v5
2.4.24	2024-09-03	45116	使 custom_collections 删除事件的消息和描述可为空
2.4.23	2024-08-31	44971	更新依赖项
2.4.22	2024-08-24	44723	更新依赖项
2.4.21	2024-08-17	44318	更新依赖项
2.4.20	2024-08-12	43834	更新依赖项
2.4.19	2024-08-10	43194	更新依赖项
2.4.18	2024-08-06	43326	为 Customer Journey Summary 流模式添加了缺失的 type 类型
2.4.17	2024-08-02	42973	修复了 no-checkpointing BULK 流的 FAILED 作业处理，修复了带有 Deleted Events 的 REST 流的 STATE 冲突
2.4.16	2024-07-21	42095	为 BULK 流添加了 Checkpointing，修复了 store 重定向
2.4.15	2024-07-27	42806	更新依赖项
2.4.14	2024-07-20	42150	更新依赖项
2.4.13	2024-07-13	41809	更新依赖项
2.4.12	2024-07-10	41103	更新依赖项
2.4.11	2024-07-09	41068	将 options 字段添加到 Product Variants 流
2.4.10	2024-07-09	41042	使用最新的 CDK: 3.0.0
2.4.9	2024-07-06	40768	更新依赖项
2.4.8	2024-07-03	40707	修复了当 product_images 流发出没有 primary_key 的记录时的错误
2.4.7	2024-06-27	40593	使用尽可能最新的 CDK 版本
2.4.6	2024-06-26	40526	使 BULK Job termination threshold 限制可从 input configuration 调整，并将默认值增加到 1 hour。
2.4.5	2024-06-25	40484	更新依赖项
2.4.4	2024-06-19	39594	扩展了 Discount Codes、Fulfillment Orders、Inventory Items、Inventory Levels、Products、Product Variants 和 Transactions 流模式
2.4.3	2024-06-06	38084	使用 HttpClient 对一些瞬态错误添加弹性
2.4.1	2024-06-20	39651	更新依赖项
2.4.0	2024-06-17	39527	添加了新的流 Order Agreements
2.3.0	2024-06-14	39487	添加了新的流 Customer Journey Summary
2.2.3	2024-06-06	38084	使用 HttpClient 对一些瞬态错误添加弹性
2.2.2	2024-06-04	39019	[autopull] 将基础镜像升级到 v1.2.1
2.2.1	2024-05-30	38769	使 products 流返回所有标签，以逗号分隔
2.2.0	2024-05-29	38746	更新了 countries 模式
2.1.4	2024-05-24	38610	将源 API Version 更新到 2024-04
2.1.3	2024-05-23	38464	为 Products 流添加了缺失的字段
2.1.2	2024-05-23	38352	将 Order Risks 流迁移到 GraphQL BULK
2.1.1	2024-05-20	38251	将 AirbyteLogger 替换为 logging.Logger
2.1.0	2024-05-02	37767	将 Products、Product Images 和 Product Variants 迁移到 GraphQL BULK
2.0.8	2024-05-02	37589	为 BULK 流添加了 HTTP 错误重试
2.0.7	2024-04-24	36660	模式描述
2.0.6	2024-04-22	37468	为 BULK 流的 Internal Server Error 添加了一次重试
2.0.5	2024-04-03	36788	添加了动态调整 slice 大小的能力
2.0.4	2024-03-22	36355	更新 CDK 版本以确保 Per-Stream 错误消息和状态中的记录计数（功能已经存在，只是提高版本）
2.0.3	2024-03-15	36170	修复了 nested 子流的 STATE 消息发射频率
2.0.2	2024-03-12	36000	修复无效商店名称导致索引超出范围错误的错误
2.0.1	2024-03-11	35952	修复了缺少 start date 但 stream 需要它的问题
2.0.0	2024-02-12	32345	修复了 state 导致 substreams 跳过记录的问题，使 metafield_*: collections, customers, draft_orders, locations, orders, product_images, product_variants, products，以及 fulfillment_orders, collections, discount_codes, inventory_levels, inventory_items, transactions_graphql, customer_address 流使用 BULK Operations 而不是 REST
1.1.8	2024-02-12	35166	使用 Poetry 管理依赖项。
1.1.7	2024-01-19	33804	更新了文档，其中包含所有受支持的流的列表
1.1.6	2024-01-04	33414	为 airbyte-lib 准备
1.1.5	2023-12-28	33827	修复 GraphQL 查询
1.1.4	2023-10-19	31599	基础镜像迁移：移除 Dockerfile 并使用 python-connector-base 镜像
1.1.3	2023-10-17	31500	修复了在设置新源时未进行身份验证时导致的 missing access token 问题
1.1.2	2023-10-13	31381	修复了在分页时使用 state 获取 deleted events 时导致的问题
1.1.1	2023-09-18	30560	性能测试 - 在 docker 镜像中包含 socat 二进制文件
1.1.0	2023-09-07	30246	添加了获取 Articles、Blogs、CustomCollections、Orders、Pages、PriceRules、Products 的 destroyed 记录的能力
1.0.0	2023-08-11	29361	迁移到 2023-07 Shopify API 版本
0.6.2	2023-08-09	29302	处理实体无法获取时的 Internal Server Error
0.6.1	2023-08-08	28291	允许 shop 字段接受 *.myshopify.com 商店名称，更新了 OAuth Spec
0.6.0	2023-08-02	28770	添加了 Disputes 流
0.5.1	2023-07-13	28700	改进了 error messages，使其更易于用户理解，重构了代码
0.5.0	2023-06-13	27732	许可证更新：Elv2
0.4.0	2023-06-13	27083	添加了 CustomerSavedSearch、CustomerAddress 和 Countries 流
0.3.4	2023-05-10	25961	为输入配置中的 shop 添加了验证（接受非 URL 样式的输入）
0.3.3	2023-04-12	25110	修复了当 cursor_field 为 "None" 时的问题，添加了流模式中缺失的属性，修复了 access_scopes 验证错误
0.3.2	2023-02-27	23473	修复了 Airbyte Cloud 的 OOM / 内存泄漏问题
0.3.1	2023-01-16	21461	将 discount_applications 添加到 orders 流
0.3.0	2022-11-16	19492	添加了 graphql 支持并添加了一个 graphql 产品流
0.2.0	2022-10-21	18298	将 API 版本更新到 2022-10，使流模式向后兼容
0.1.39	2022-10-13	17962	添加了 metafield 流；支持嵌套列表流
0.1.38	2022-10-10	17777	修复了配置流的 404，修复了旧记录的缺失 cursor 错误
0.1.37	2022-04-30	12500	改进了输入配置复制
0.1.36	2022-03-22	9850	添加了 BalanceTransactions 流
0.1.35	2022-03-07	10915	修复了一个导致为 incremental 配置的子 REST 实体的 full-refresh 同步的问题
0.1.34	2022-03-02	10794	次要规范重新排序，修复了文档中的链接
0.1.33	2022-02-17	10419	修复了 Abandoned_checkouts 流中 tax_exemptions 的错误字段类型
0.1.32	2022-02-18	10449	添加了 tender_transactions 流
0.1.31	2022-02-08	10175	修复了旧版用户配置的兼容性问题
0.1.30	2022-01-24	9648	添加了同步前的权限验证
0.1.29	2022-01-20	9248	为所有流的记录添加了 shop_url
0.1.28	2022-01-19	9591	为 Airbyte Cloud 实现了 OAuth2.0 身份验证方法
0.1.27	2021-12-22	9049	更新了连接器字段标题/描述
0.1.26	2021-12-14	8597	修复了基本规范化中的 mismatched number of tables，提高了 order_refunds 流的性能
0.1.25	2021-12-02	8297	添加了 Shop 流
0.1.24	2021-11-30	7783	审查并更正了所有流的模式
0.1.23	2021-11-15	7973	添加了 InventoryItems
0.1.22	2021-10-18	7107	添加了 FulfillmentOrders、Fulfillments 流
0.1.21	2021-10-14	7382	修复了 InventoryLevels 主键
0.1.20	2021-10-14	7063	添加了 Location 和 InventoryLevels 作为流
0.1.19	2021-10-11	6951	添加了对 OAuth 2.0 授权选项的支持
0.1.18	2021-09-21	6056	将 pre_tax_price 添加到 orders/line_items 模式
0.1.17	2021-09-17	5244	创建了将价格转换为数字的数据类型强制执行器
0.1.16	2021-09-09	5945	修复了连接器的 Incremental refresh 性能
0.1.15	2021-09-02	5853	修复了 order_refund 模式中的 amount 类型
0.1.14	2021-09-02	5801	修复了 orders 模式中 line_items/discount allocations 和 duties 部分
0.1.13	2021-08-17	5470	修复了速率限制节流
0.1.12	2021-08-09	5276	为产品模式添加了状态属性
0.1.11	2021-07-23	4943	修复了产品模式，最高到 API 2021-07
0.1.10	2021-07-19	4830	修复了流 json 模式，升级到 API 版本 2021-07
0.1.9	2021-07-04	4472	增量同步现在默认使用 updated_at 而不是 since_id
0.1.8	2021-06-29	4121	添加了草稿订单流
0.1.7	2021-06-26	4290	修复了将输出记录限制为 1 导致无限循环的错误
0.1.6	2021-06-24	4009	添加了页面、价格规则和折扣代码流
0.1.5	2021-06-10	3973	添加了 AIRBYTE_ENTRYPOINT 以支持 Kubernetes
0.1.4	2021-06-09	3926	新的订单模式属性
0.1.3	2021-06-08	3787	添加了 Native Shopify 来源连接器