2018年5月,我们宣布Shopify的管理APIGraphQL,作为一个现代的、强大的、更容易使用的API供您构建。使用GraphQL是与api交互的一种令人兴奋的方式,并为应用程序开发人员打开了一个全新的可能性世界。
无论您是希望有效地检索有关几个不同相关对象的信息,还是仅仅获取一个信息字段而不消耗REST调用限制的重要部分,现在都是了解如何使用我们的GraphQL管理API。
为了帮助您利用GraphQL中Admin API提供的所有可能性,我们整理了这个学习工具包。它将指导您通过对Shopify GraphQL管理API的各种调用,使用失眠API客户端。
为Shopify商家构建应用程序
无论您是想为Shopify App Store构建应用程序,提供私人应用程序开发服务,还是正在寻找增加用户基础的方法,Shopify合作伙伴计划都将为您的成功奠定基础。免费加入并访问教育资源、开发人员预览环境和经常性收入分享机会。
报名1.先决条件
为了跟随这个演练,你需要一些东西:
- 你自己的你在商店里创建的私有应用
- 它将需要读写权限来:
- 产品
- 客户
- 订单
- DraftOrders
- 点击“查看禁用的Admin API权限”,向下滚动到底部找到最后一个权限
- 的失眠API客户端
- 的Shopify GraphQL攻略失眠集合
如何配置失眠
安装失眠之后,需要导入集合并确保正确配置它,以便使用API凭证调用商店。下面是这样做的步骤。
步骤1:导入集合
一旦你将演练作为一个集合下载,你需要把它导入失眠系统。
打开导入/导出失眠的窗口:
从数据选项卡,浏览到集合:
切换到Shopify GraphQL工作区:
步骤2:配置环境变量
环境变量是JSON键值对,允许您引用值,而不必每次都将它们写出来。
对于我们的设置,我们将定义两个环境变量:
- 的
商店
我们将与 - 如果你的商店是mydevstore.myshopify.com,在这里输入“mydevstore”
- 的
access_token
我们将使用 - 这是你的私人应用的密码,在该应用的页面上可见
这将使您能够在不同的Shopify商店中重用此集合中的所有查询,只需更改失眠环境变量。
控件来设置环境变量管理环境窗口,并将详细信息添加到my-test-store-details子:
步骤3:运行测试查询
现在是时候进行测试了。
在失眠中,打开第二个查询,在下面Shopify GraphQL攻略>失眠配置名为运行其余查询。
您应该在框架的顶部看到,我们正在使用“store”来构建端点的地址。
你也可以点击头在顶部查看我们随请求发送的标头,包括access_token
。
将鼠标悬停在其中任何一个上,应该会显示将被替换到请求中的值。
如果你没有看到你的价值,确保你选择了正确的环境。
在环境中设置好这两个字段之后,尝试运行下面的查询。你应该要回你的店名。
2.查询结构示例
让我们从学习OB欧宝娱乐APP如何构建查询以充分利用GraphQL开始。
QueryRoot对象
的QueryRoot表示易于访问GraphQL管理API图的入口点。
要使用此页,请在该页中搜索您感兴趣的资源,然后单击以了解更多信息。
在我们的示例中,我们将再次查看Shop资源,因为它是单个对象。对象表示概念,例如商店,或者一个订单,并在字段中包含数据。
在GraphQL中,我们总是必须从可用字段中选择我们想要返回给我们的内容。另外,当你选择字段时,失眠会自动完成有效的字段,所以你可以随意修改下面的查询,以获得更多或更少的信息。
该查询获取Shop对象,并指定我们希望返回哪些字段。
你可能会注意到你得到了你想要的,然后更多。在返回的JSON有效负载中,您应该看到两个顶级键:“data”和“extensions”。
- “数据”始终是您刚刚在查询中请求的内容
- “扩展”是Shopify添加的额外信息,例如查询的成本
我们会仔细看看的成本下次吧,所以现在不用担心。
连接和边
连接是相关对象之间的链接。这允许您进行嵌套查询,通过在单个GraphQL调用中遍历多个对象的连接来收集来自多个对象的信息。
当使用连接时,您需要选择“edges”字段。edges字段是相同类型的对象数组,例如商店的订单。一旦你选择了边,你会想要通过节点字段访问单个对象。
在节点字段中,您可以选择想要返回的对象字段。这些字段将在边缘数组中的每个对象上被选中。
最后,在使用连接时,您总是需要选择希望返回的对象数量(集合中的第一个或最后一个)。更多关于这一点,在下面分页部分。
该查询获取产品的连接(可从QueryRoot获得),并请求前三个产品。它从每个返回的产品对象中选择边、节点和字段。
由于产品也有变体连接,因此我们重复类似的过程来获取每个产品的前五个变体的信息。
使用query参数过滤连接
在许多连接中,你会想要过滤掉边缘列表以找到你真正感兴趣的特定对象(即特定的节点
的集合边缘
).
方法来查找连接支持过滤的字段查询
参数在文档中该连接的参考页上。至于格式化过滤器,语法遵循搜索语法所指导。
该查询查找完成的前十个订单。
单对象ID
通过联系获得信息很好,但有时我们可能想要更直接的东西。
值得庆幸的是,我们还可以通过对象的GraphQL ID直接访问对象。
看看我们的QueryRoot文档中,我们可以看到有多个查询需要单个GraphQL ID作为输入,并返回该对象。最好总是选择要查询的任何对象的ID,以便以后可以直接引用它。
请注意确保这里使用的是GraphQL ID,而不仅仅是复制粘贴REST ID。
的从REST指南迁移有更多关于从REST获取GraphQL id的信息。
该查询通过ID获取单个产品,并指定我们希望返回哪些字段。
您可以很容易地从对前面“连接和边缘”查询的响应中获得该查询的产品的GraphQL ID。如果您不这样做,您将得到一个“null”响应,因为您正在寻找一个在您的商店中不存在的产品ID。
3.突变结构例子
现在我们已经了解了使用GraphQL请求数据的来龙去龙去,我们将着手修改它。
基础知识和输入
突变相当于REST的POST/PUT/DELETE操作,允许您创建和修改对象。它们不直接与资源绑定,因此确定它们将做什么通常归结为命名约定和阅读文档。
与查询一样,在GraphQL中,您必须始终选择希望返回的数据。通常,突变将返回创建/修改的对象,这为您提供了选择GraphQL ID(特别是在创建之后)以及验证任何关键数据的绝佳机会。
最后,突变总是包含auserErrors
字段。这个字段让您知道您的突变是否有什么问题,以及为什么它没有按照预期进行处理。
你应该总是选择userErrors
字段来帮助您自己进行故障排除。如果没出什么差错的话userErrors
字段将为空。
这个突变创建了一个新客户。我们还传入了输入,这是一个JSON对象,其中包含我们希望客户拥有的数据。
突变通常需要输入,您可以通过检查文档查看可以将哪些字段添加到这个输入散列中。首先,观察突变,看看它期望什么样的输入。其次,检查该输入的文档中所有可用的字段。例如,的CustomerInput
页面列出所有可用的输入。
请注意如果你得到一个“访问拒绝”错误信息,确保你的应用程序有客户读/写权限。
我们也将选择这些字段,以确认它们已被正确设置。
输入v2
突变输入也可能需要id,例如在创建订单时。
通过之前的修改,您应该在创建之后收到客户的GraphQL ID(如果您选择了它)。让我们继续使用它为这个客户创建一个新的汇票订单。
为了正确格式化我们的输入,我们将参考参考文档draftOrderCreate,DraftOrderInput,DraftOrderLineItemInput。
失眠应该从可用的字段中自动完成字段名,所以文档不是完全必要的,因为失眠会自动加载模式。
请注意如果你得到一个“Access Denied”错误信息,确保你的应用程序有DraftOrders读/写权限。
4.GraphQL变量
为了加速和重用我们的工作,我们将利用GraphQL的本地变量实现。
变量
GraphQL变量允许您使用不同的参数重用相同的查询/变更。
在Insomnia中,查询变量被分隔到编辑器的下部。对于下面的每个示例,都必须将值添加到变量中。如果不这样做,则意味着您将尝试查询我的商店的数据,并且您应该收到“null”响应。
在我们的示例中,让我们找到刚刚创建的草稿订单,并使用作为变量一部分返回给我们的ID。
让我们逐行执行,看看如何将变量拉入查询中。
5.分页
为了优化我们查询的数据量,让我们看一下如何在GraphQL中遍历对象。
什么是pageInfo?
当请求连接时,我们必须总是请求完整结果的一个子集,带有“first”或“last”参数。这意味着当查看“订单”时,我们将只看到前X个订单,然后能够从这些订单中选择我们想要的字段。这对于出现在第一个(或最后一个)X的道具来说非常好,但我们如何获得更多中心元素呢?
在每个连接中,都有一个“pageInfo”字段,与边缘处于同一级别。pageInfo字段包含有关我们所请求的连接的当前子集的信息。值得注意的是,我们希望检查“hasNextPage”字段,如果连接中有更多当前子集未显示的元素,则返回true。
该查询获取前10个订单,并询问是否还有更多订单。
光标
对于分页,知道连接中存在下一组(X个对象)是不够的。我们还必须找到一种方法来指代它。
游标是对连接边缘上下文中节点(对象)的引用。通过稍微修改我们的查询,我们可以请求在游标之前或之后的节点。
让我们再看一下前面的查询,并请求当前边缘的光标。
该查询获取前10个订单,并询问是否还有更多订单。它还要求获取那条边的光标。
游标v2
有了游标,我们就完全可以遍历整个连接了。
在每个连接上,都可以指定“after”参数,该参数告诉服务器在指定游标之后向您返回结果。使用前一个查询中为“cursor”返回的值作为此查询中的“after”参数,以获取下一组边。不要忘记用您自己的值替换包含的游标变量值。
请注意这在本质上相当于在REST管理API上使用“since_id”。
让我们再看一下前面的查询,并请求当前边缘的光标。
6.先进的
至此,您已经了解了开始GraphQL之旅所需的一切。OB欧宝娱乐APP如果你仍然渴望获得提示和技巧,请继续阅读。
片段:处理多个案例
片段是一个GraphQL概念,它允许您直接在查询中构建一些灵活性。它们的标志是“……”on
使用QueryRoot上的“node”字段,我们可以通过特定对象的ID请求它们。这将返回对象(在“node”字段下或作为“nodes”连接下的边)作为具有基本类型的节点对象,这将不允许我们请求任何更深层次的信息。然而,使用片段,如果节点是该类型,我们可以请求更具体的类型数据。这对于不容易通过QueryRoot访问的节点(例如单个lineItem)特别有用。
让我们使用到目前为止学到的所有知识来查找lineItem的库存位置,以便我们可以从该位置完成它。
该查询使用节点QueryRoot字段。我们请求一个从某处获得的ID,比如前一个订单或游标查询中的行项。
多个查询:一个请求
您可以在单个GraphQL请求中提交多个查询或变更。这实际上没有任何速率限制的好处,因为查询复杂性仍然是加在一起的,但是对于任何其他使您更容易发送一个多请求的约束,这就是如何做到这一点。
要点是:
- 在顶部声明类型,查询或突变
- 必须为每个单独的查询命名
< your-custom-name >: <查询/ mutation-name-you-are-invoking >
- 查询不必相同
- 每个单独的查询必须选择它想要返回的字段
这种多重突变在三个不同的客户身上设置了三个不同的标签。
为Shopify商家构建应用程序
无论您是想为Shopify App Store构建应用程序,提供私人应用程序开发服务,还是正在寻找增加用户基础的方法,Shopify合作伙伴计划都将为您的成功奠定基础。免费加入并访问教育资源、开发人员预览环境和经常性收入分享机会。
报名