示例说明

一个维格表可能存在多个字段（列），而开发者根据业务场景，可能只需要获取其中几个字段。

回想一下，在一些商城 APP 里，是不是有 “商品列表” 和 “商品详情” 这两种不同的页面？它们的用途不同，所以页面展示的信息也不同。在 “商品列表” 里，商品图、商品标题、价格这三个字段是必要信息；而在 “商品详情” 里，除了这三个字段，还会包含其它更多的字段，如卖点、分类等。

假设所有字段数据都存放在同一个维格表里，如何根据业务场景不同，从而返回不同的字段列表呢？

sample-get-records-4.jpg


通过 fields 参数，开发者可指定 API 请求要返回的字段列表，具体调用方法请跟随本示例一步一步往下学习。




样本数据

API 文档里所使用的样本数据，皆可通过此分享链接获得：《API 教程样本数据》，建议另存到自己的空间站，然后跟着例子一步一步学习，事半功倍哦！

本示例将使用分享链接里的「样本数据2 - 商品列表」展开讲解。

教程示例数据




操作步骤

步骤一：将样本数据另存到自己的空间站里，然后访问「样本数据2 - 商品列表」。

步骤二：打开 “API 示例面板”，查找“标题”，“分类”，“主要卖点”，“原价”，“配图” 这五个字段的 Field ID。（此步骤可跳过，如果参数 fieldKey=name则无需使用 Field ID）

sample-get-records-5.png


步骤三：

调用 API「获取记录」，使用请求参数 recordIds 并带上第二条和第四条记录的 ID（ recSmw20itN9E , recgmPxp7gQTH ）。


请注意： fields 参数需要配合 fieldKey 参数一同使用才能生效。根据 fieldKey 的值不同，调用 API 「获取记录」可分为下列两种方式：

① 当 fieldKey=id 时， 请求参数 fields 的值必须使用字段的 ID（ 例如：fldX6vUsYDStY , fld1K524XGsxE， fldj2NZ8PWrSS，fldAZpuovQWFN， fldekQH8WIekz ）。

此方法的优点是：由于字段 ID 固定且唯一，所以在维格视图下修改列（ 字段 ）名称不会影响到 API 调用。


② 当 fieldKey=name 时， 请求参数 fields 的值必须使用字段的名称（ 例如：“标题”，“分类”，“主要卖点”，“原价”，“配图” ）。如果开发者调用 API 时不显式指定 fieldKey 参数，则默认使用 “name” 作为缺省值。

此方法更简单直观，更语义化，但代码容易受影响，当字段名称（列名）发生变化后，都需要修改代码。


步骤四：维格表服务端接收到请求后，返回的记录数据里只会包含 “标题”，“分类”， “主要卖点”，“原价”，“配图” 这五个字段的值。




API 调用


参数：fields

参数类型：字符串数组（Array Of Strings）

指定要返回的字段（默认为字段名, 也可以通过 fieldKey 指定为字段 Id ）。

如果附带此参数，则返回的记录合集将会被过滤，只有指定的字段会返回。


兼容如下几种格式规范（为了易读性，下方格式使用字段名称，即 fieldKey="name" 展开说明）：

格式 1：fields=标题,原价,摘要
注意：此格式必须使用半角逗号作为分隔符，且字段名称左右两边不能有空白字符

格式 2：fields=标题&fields=原价&fields=摘要

格式 3：fields[]=标题&fields[]=原价&fields[]=摘要


① cURL 示意：

注意：下方代码为了直观显示参数的结构，没有转义编码。正式调用时，请使用 encodeURIComponent() 函数对 URL 参数进行转义编码。

// 编码前
curl 'https://api.vika.cn/fusion/v1/datasheets/dstdQxaqwGaoBbB8bK/records?fields=标题,原价,摘要' \
  -H 'Authorization: Bearer {_替换成你的API_Token_}' 

// 编码后
curl 'https://api.vika.cn/fusion/v1/datasheets/dstdQxaqwGaoBbB8bK/records?fields=%E6%A0%87%E9%A2%98%2C%E5%8E%9F%E4%BB%B7%2C%E6%91%98%E8%A6%81' \
  -H 'Authorization: Bearer {_替换成你的API_Token_}'


② 调试工具示意：

fields_方式1

fields_方式2

fields_方式3


返回结果：

正常情况下，维格表服务端会返回下述 JSON 数据包

{
    "code": 200,
    "success": true,
    "data": {
        "total": 25,
        "pageNum": 1,
        "pageSize": 25,
        "records": [
            {
                "recordId": "recuT3HD7Jgdy",
                "createdAt": 1610103747000,
                "updatedAt": 1610103747000,
                "fields": {
                    "标题": "即热饮水机 6挡水温",
                    "原价": 399,
                    "摘要": "即热即饮，6段水温，一键任意杯量，1.8L水箱容量"
                }
            },
            {
                "recordId": "rec6f5x1www8n",
                "createdAt": 1610103747000,
                "updatedAt": 1610103747000,
                "fields": {
                    "标题": "搅拌料理机Pro",
                    "原价": 199,
                    "摘要": "6叶镀钛刀头/便携运动杯/3万转高速电机/可选配研磨杯配件"
                }
            },
            //...more
        ]
    },
    "message": "SUCCESS"
}

results matching ""

    No results matching ""