Shopify GraphQL学习工具包

shopify-graphql-learning-kit

2018年5月,我们宣布Shopify的管理APIGraphQL,作为一个现代的、强大的、更容易使用的API供您构建。使用GraphQL是与api交互的一种令人兴奋的方式,并为应用程序开发人员打开了一个全新的可能性世界。

无论您是希望有效地检索有关几个不同相关对象的信息,还是仅仅获取一个信息字段而不消耗REST调用限制的重要部分,现在都是了解如何使用我们的GraphQL管理API

为了帮助您利用GraphQL中Admin API提供的所有可能性,我们整理了这个学习工具包。它将指导您通过对Shopify GraphQL管理API的各种调用,使用失眠API客户端

为Shopify商家构建应用程序

无论您是想为Shopify App Store构建应用程序,提供私人应用程序开发服务,还是正在寻找增加用户基础的方法,Shopify合作伙伴计划都将为您的成功奠定基础。免费加入并访问教育资源、开发人员预览环境和经常性收入分享机会。

报名

1.先决条件

为了跟随这个演练,你需要一些东西:

shopify-graphql-learning-kit-admin
确保您的私人应用程序具有对产品,客户,订单和草稿订单的读写权限。点击检查禁用的Admin API权限来访问DraftOrders。

已经是一位经验丰富的GraphQL老手了吗?

直接点击下面链接的要点来复制请求,而不必使用失眠。

视图要点

如何配置失眠

安装失眠之后,需要导入集合并确保正确配置它,以便使用API凭证调用商店。下面是这样做的步骤。

步骤1:导入集合

一旦你将演练作为一个集合下载,你需要把它导入失眠系统。

打开导入/导出失眠的窗口:

shopify-graphql-learning-kit-import-export

数据选项卡,浏览到集合:

shopify-graphql-learning-kit-walkthrough

切换到Shopify GraphQL工作区:

shopify-graphql-learning-kit-walkthrough

步骤2:配置环境变量

环境变量是JSON键值对,允许您引用值,而不必每次都将它们写出来。

对于我们的设置,我们将定义两个环境变量:

  • 商店我们将与
    • 如果你的商店是mydevstore.myshopify.com,在这里输入“mydevstore”
    • access_token我们将使用
      • 这是你的私人应用的密码,在该应用的页面上可见
      shopify-graphql-learning-kit-password
      您的私人应用程序的密码可见在您的应用程序页面。

      这将使您能够在不同的Shopify商店中重用此集合中的所有查询,只需更改失眠环境变量。

      控件来设置环境变量管理环境窗口,并将详细信息添加到my-test-store-details子:

      shopify-graphql-learning-kit-manage-environments
      打开管理环境窗口。
      shopify-graphql-learning-kit-my-test-store-details
      添加您的详细信息到my-test-store-details子。

      步骤3:运行测试查询

      现在是时候进行测试了。

      在失眠中,打开第二个查询,在下面Shopify GraphQL攻略>失眠配置名为运行其余查询

      您应该在框架的顶部看到,我们正在使用“store”来构建端点的地址。

      你也可以点击在顶部查看我们随请求发送的标头,包括access_token

      将鼠标悬停在其中任何一个上,应该会显示将被替换到请求中的值。

      如果你没有看到你的价值,确保你选择了正确的环境。

      shopify-graphql-learning-kit-query-environment
      确保您选择了正确的环境。查看要点

      在环境中设置好这两个字段之后,尝试运行下面的查询。你应该要回你的店名。

      shopify-graphql-learning-kit-run-test-query
      运行查询以获得您的商店名称。

      2.查询结构示例

      让我们从学习OB欧宝娱乐APP如何构建查询以充分利用GraphQL开始。

      QueryRoot对象

      QueryRoot表示易于访问GraphQL管理API图的入口点。

      要使用此页,请在该页中搜索您感兴趣的资源,然后单击以了解更多信息。

      在我们的示例中,我们将再次查看Shop资源,因为它是单个对象。对象表示概念,例如商店,或者一个订单,并在字段中包含数据。

      在GraphQL中,我们总是必须从可用字段中选择我们想要返回给我们的内容。另外,当你选择字段时,失眠会自动完成有效的字段,所以你可以随意修改下面的查询,以获得更多或更少的信息。

      该查询获取Shop对象,并指定我们希望返回哪些字段。

      shopify-graphql-learning-kit-query-root-objects
      查询以获取带有某些字段的Shop对象。查看要点

      你可能会注意到你得到了你想要的,然后更多。在返回的JSON有效负载中,您应该看到两个顶级键:“data”和“extensions”。

      • “数据”始终是您刚刚在查询中请求的内容
      • “扩展”是Shopify添加的额外信息,例如查询的成本

      我们会仔细看看的成本下次吧,所以现在不用担心。

      连接和边

      连接是相关对象之间的链接。这允许您进行嵌套查询,通过在单个GraphQL调用中遍历多个对象的连接来收集来自多个对象的信息。

      当使用连接时,您需要选择“edges”字段。edges字段是相同类型的对象数组,例如商店的订单。一旦你选择了边,你会想要通过节点字段访问单个对象。

      在节点字段中,您可以选择想要返回的对象字段。这些字段将在边缘数组中的每个对象上被选中。

      最后,在使用连接时,您总是需要选择希望返回的对象数量(集合中的第一个或最后一个)。更多关于这一点,在下面分页部分

      该查询获取产品的连接(可从QueryRoot获得),并请求前三个产品。它从每个返回的产品对象中选择边、节点和字段。

      由于产品也有变体连接,因此我们重复类似的过程来获取每个产品的前五个变体的信息。

      shopify-graphql-learning-kit-query-variants
      查询前三个产品的产品连接。查看要点

      使用query参数过滤连接

      在许多连接中,你会想要过滤掉边缘列表以找到你真正感兴趣的特定对象(即特定的节点的集合边缘).

      方法来查找连接支持过滤的字段查询参数在文档中该连接的参考页上。至于格式化过滤器,语法遵循搜索语法所指导

      该查询查找完成的前十个订单。

      shopify-graphql-learning-kit-query-first-orders
      查询前10个已完成的订单。查看要点

      单对象ID

      通过联系获得信息很好,但有时我们可能想要更直接的东西。

      值得庆幸的是,我们还可以通过对象的GraphQL ID直接访问对象。

      看看我们的QueryRoot文档中,我们可以看到有多个查询需要单个GraphQL ID作为输入,并返回该对象。最好总是选择要查询的任何对象的ID,以便以后可以直接引用它。

      请注意确保这里使用的是GraphQL ID,而不仅仅是复制粘贴REST ID。

      从REST指南迁移有更多关于从REST获取GraphQL id的信息。

      该查询通过ID获取单个产品,并指定我们希望返回哪些字段。

      您可以很容易地从对前面“连接和边缘”查询的响应中获得该查询的产品的GraphQL ID。如果您不这样做,您将得到一个“null”响应,因为您正在寻找一个在您的商店中不存在的产品ID。

      shopify-graphql-learning-kit-accessing-object
      通过对象的GraphQL ID直接访问对象。查看要点

      3.突变结构例子

      现在我们已经了解了使用GraphQL请求数据的来龙去龙去,我们将着手修改它。

      基础知识和输入

      突变相当于REST的POST/PUT/DELETE操作,允许您创建和修改对象。它们不直接与资源绑定,因此确定它们将做什么通常归结为命名约定和阅读文档。

      与查询一样,在GraphQL中,您必须始终选择希望返回的数据。通常,突变将返回创建/修改的对象,这为您提供了选择GraphQL ID(特别是在创建之后)以及验证任何关键数据的绝佳机会。

      最后,突变总是包含auserErrors字段。这个字段让您知道您的突变是否有什么问题,以及为什么它没有按照预期进行处理。

      你应该总是选择userErrors字段来帮助您自己进行故障排除。如果没出什么差错的话userErrors字段将为空。

      这个突变创建了一个新客户。我们还传入了输入,这是一个JSON对象,其中包含我们希望客户拥有的数据。

      突变通常需要输入,您可以通过检查文档查看可以将哪些字段添加到这个输入散列中。首先,观察突变,看看它期望什么样的输入。其次,检查该输入的文档中所有可用的字段。例如,CustomerInput页面列出所有可用的输入。

      请注意如果你得到一个“访问拒绝”错误信息,确保你的应用程序有客户读/写权限。

      我们也将选择这些字段,以确认它们已被正确设置。

      shopify-graphql-learning-kit-customer-create-mutation
      使用customerCreate变量创建客户。查看要点

      输入v2

      突变输入也可能需要id,例如在创建订单时。

      通过之前的修改,您应该在创建之后收到客户的GraphQL ID(如果您选择了它)。让我们继续使用它为这个客户创建一个新的汇票订单。

      为了正确格式化我们的输入,我们将参考参考文档draftOrderCreateDraftOrderInput,DraftOrderLineItemInput

      失眠应该从可用的字段中自动完成字段名,所以文档不是完全必要的,因为失眠会自动加载模式。

      请注意如果你得到一个“Access Denied”错误信息,确保你的应用程序有DraftOrders读/写权限。

      shopify-graphql-learning-kit-draft-order-create-mutation
      使用draftOrderCreate变量创建一个草稿订单。查看要点

      4.GraphQL变量

      为了加速和重用我们的工作,我们将利用GraphQL的本地变量实现。

      变量

      GraphQL变量允许您使用不同的参数重用相同的查询/变更。

      在Insomnia中,查询变量被分隔到编辑器的下部。对于下面的每个示例,都必须将值添加到变量中。如果不这样做,则意味着您将尝试查询我的商店的数据,并且您应该收到“null”响应。

      在我们的示例中,让我们找到刚刚创建的草稿订单,并使用作为变量一部分返回给我们的ID。

      让我们逐行执行,看看如何将变量拉入查询中。

      shopify-graphql-learning-kit-reusable-query
      使用GraphQL变量创建可重用查询。查看要点

      5.分页

      为了优化我们查询的数据量,让我们看一下如何在GraphQL中遍历对象。

      什么是pageInfo?

      当请求连接时,我们必须总是请求完整结果的一个子集,带有“first”或“last”参数。这意味着当查看“订单”时,我们将只看到前X个订单,然后能够从这些订单中选择我们想要的字段。这对于出现在第一个(或最后一个)X的道具来说非常好,但我们如何获得更多中心元素呢?

      在每个连接中,都有一个“pageInfo”字段,与边缘处于同一级别。pageInfo字段包含有关我们所请求的连接的当前子集的信息。值得注意的是,我们希望检查“hasNextPage”字段,如果连接中有更多当前子集未显示的元素,则返回true。

      该查询获取前10个订单,并询问是否还有更多订单。

      shopify-graphql-learning-kit-page-info-retrieve
      使用pageInfo来确定是否有其他页面需要检索。查看要点

      光标

      对于分页,知道连接中存在下一组(X个对象)是不够的。我们还必须找到一种方法来指代它。

      游标是对连接边缘上下文中节点(对象)的引用。通过稍微修改我们的查询,我们可以请求在游标之前或之后的节点。

      让我们再看一下前面的查询,并请求当前边缘的光标。

      该查询获取前10个订单,并询问是否还有更多订单。它还要求获取那条边的光标。

      shopify-graphql-learning-kit-select-cursor
      选择光标。查看要点

      游标v2

      有了游标,我们就完全可以遍历整个连接了。

      在每个连接上,都可以指定“after”参数,该参数告诉服务器在指定游标之后向您返回结果。使用前一个查询中为“cursor”返回的值作为此查询中的“after”参数,以获取下一组边。不要忘记用您自己的值替换包含的游标变量值。

      请注意这在本质上相当于在REST管理API上使用“since_id”。

      让我们再看一下前面的查询,并请求当前边缘的光标。

      shopify-graphql-learning-kit-cursor-paginate
      使用游标进行分页。查看要点

      6.先进的

      至此,您已经了解了开始GraphQL之旅所需的一切。OB欧宝娱乐APP如果你仍然渴望获得提示和技巧,请继续阅读。

      片段:处理多个案例

      片段是一个GraphQL概念,它允许您直接在查询中构建一些灵活性。它们的标志是“……”on "语法。

      使用QueryRoot上的“node”字段,我们可以通过特定对象的ID请求它们。这将返回对象(在“node”字段下或作为“nodes”连接下的边)作为具有基本类型的节点对象,这将不允许我们请求任何更深层次的信息。然而,使用片段,如果节点是该类型,我们可以请求更具体的类型数据。这对于不容易通过QueryRoot访问的节点(例如单个lineItem)特别有用。

      让我们使用到目前为止学到的所有知识来查找lineItem的库存位置,以便我们可以从该位置完成它。

      该查询使用节点QueryRoot字段。我们请求一个从某处获得的ID,比如前一个订单或游标查询中的行项。

      shopify-graphql-learning-kit-transversing-connections
      遍历连接以确定行项在哪里有库存。查看要点

      多个查询:一个请求

      您可以在单个GraphQL请求中提交多个查询或变更。这实际上没有任何速率限制的好处,因为查询复杂性仍然是加在一起的,但是对于任何其他使您更容易发送一个多请求的约束,这就是如何做到这一点。

      要点是:

      1. 在顶部声明类型,查询或突变
      2. 必须为每个单独的查询命名< your-custom-name >: <查询/ mutation-name-you-are-invoking >
      3. 查询不必相同
      4. 每个单独的查询必须选择它想要返回的字段

      这种多重突变在三个不同的客户身上设置了三个不同的标签。

      shopify-graphql-learning-kit-multiple-mutations
      在单个调用中执行多个突变。查看要点

      今天就将GraphQL添加到您的应用程序中

      通过这组查询,您可以看到Shopify GraphQL管理API是多么快速和灵活。它能够在一次调用中访问多个对象的数据,并为您提供所需的特定数据,GraphQL保证提高应用程序的功能,并在此过程中为您节省了一些REST调用。

      为Shopify商家构建应用程序

      无论您是想为Shopify App Store构建应用程序,提供私人应用程序开发服务,还是正在寻找增加用户基础的方法,Shopify合作伙伴计划都将为您的成功奠定基础。免费加入并访问教育资源、开发人员预览环境和经常性收入分享机会。

      报名
      主题:

      借助Shopify合作伙伴计划发展您的业务

      了解更多