开放接口创建卡片实例

本文介绍了通过开放接口创建卡片实例。

说明

在创建卡片实例之前，确保你已经完成了以下的准备工作：

在卡片平台上完成卡片模板搭建及发布

简介

前文提到互动卡片是由卡片模板和卡片数据构成的，创建卡片实例是将卡片模板和卡片数据关联起来进行实例化的过程。完成创建后即可针对卡片实例进行数据更新、投放等操作。详情参见创建卡片接口。

卡片数据

卡片的数据分为公共数据和私有数据，公共数据是所有用户都可见的数据，私有数据是只有每个用户自己可见的数据。创建卡片的时候可以设置卡片实例的公共数据和私有数据。

创建卡片后，也可以通过卡片更新来主动更新卡片的公共数据和私有数据。

动态数据源属性

卡片的公共数据和私有数据都是存储在卡片服务端的，同时，卡片也允许用户将一些敏感、需要定时更新，或者需要针对不同人定制的数据，存放在用户处。这种数据叫动态数据，卡片服务端会根据用户在创建卡片时配置的规则，到用户处拉取数据。对于拉取到的数据，卡片服务端不会进行存储，而是直接渲染卡片。更多详情参见动态数据源。

多场域属性

一张卡片可以同时存在于多个场域，例如一张在 IM 群聊里的卡片可以同时出现在协作页面或者群聊吊顶中。如果卡片需要投放到某个场域，那么需要在创建的时候就在卡片实例上添加该场域的属性。例如，如果卡片需要投放到 IM 群聊场域中，可以配置卡片在该场域下的通知内容、是否支持转发等。

下图展示了一张同时存在于 IM 群聊、吊顶和协作三个场域中的卡片。

目前可用的场域、以及如何配置和添加场域信息参见：

通过服务端API-创建卡片接口，实现场域的添加。

通过服务端API-新增或者更新卡片的场域信息接口，实现对场域信息的添加和更新操作，详情参见开放接口投放卡片实例。

步骤一：创建卡片

一张基本的卡片可以包含这几个基本信息：

userId：创建卡片的用户的 ID，非必填

userIdType：卡片使用的用户 ID 的类型，1 为 userId 模式，2 为 unionId 模式，默认为 1

cardTemplateId：卡片模板的 ID，在卡片模板搭建及发布后获取

outTrackId：卡片 ID。这是开发者自定义的，后续对卡片的投放和互动操作，均是通过 outTrackId 来完成

cardData：卡片的公共数据

privateData：卡片的私有数据

调用服务端API-创建卡片接口实现卡片实例的创建。

HTTP

POST /v1.0/card/instances HTTP/1.1
Host:api.dingtalk.com
x-acs-dingtalk-access-token:String
Content-Type:application/json

{
  "userId" : "example-user-id",
  "userIdType": 1,
  "cardTemplateId" : "example-template-id",
  "outTrackId" : "example-out-track-id",
  "cardData" : {
    "cardParamMap" : {
      "param1" : "example_value"				    // 模板上配置的卡片参数
    }
  },
  "privateData" : {
    "example_user_id" : {								    // 用户 ID
      "cardParamMap" : {
        "privateParam1" : "example_value"   // 模板上配置的卡片私有参数
      }
    }
  }
}

说明

卡片非 String 类型属性的填写请参考：API 卡片数据的填写说明。

userIdType 字段的填写请参考：userIdType 字段的填写说明。

步骤二：设置卡片的高级属性

如果想使用卡片的高级功能，比如多场域或者动态数据源，要在上述创建卡片步骤的基础上，设置卡片的多场域属性或者动态数据源属性。

添加多场域属性

卡片在投放到某个场域之前，需要在卡片上配置该场域的属性。卡片的场域属性可以在创建的时候配置，也可以在创建后补加。下面介绍在创建卡片的时候配置场域属性，如何在创建好的卡片上添加场域属性以及将卡片投放到场域，详情参见开放接口投放卡片实例。

HTTP

POST /v1.0/card/instances HTTP/1.1
Host:api.dingtalk.com
x-acs-dingtalk-access-token:String
Content-Type:application/json

{
  "userId" : "example_user_id",
  "userIdType": 1,
  "cardTemplateId" : "example_template_id",
  "outTrackId" : "example_out_track_id",
  "cardData" : {
    "cardParamMap" : {
      "param1" : "example_value"				    // 模板上配置的卡片参数
    }
  },
  "privateData" : {
    "example_user_id" : {								    // 用户 ID
      "cardParamMap" : {
        "privateParam1" : "example_value"   // 模板上配置的卡片私有参数
      }
    }
  },
  "imGroupOpenSpaceModel" : {
    "supportForward" : false,
    "lastMessageI18n" : {
       "ZH_CN": "卡片", 
       "EN_US": "card"
    },
    "searchSupport" : {
      "searchIcon" : "@lALPDgQ9q8hFhlHNAXzNAqI",
      "searchTypeName" : "{\"zh_CN\":\"示例\",\"zh_TW\":\"示例\",\"en_US\":\"Example\"}",
      "searchDesc" : "卡片的具体描述"
    },
    "notification" : {
      "alertContent" : "你收到了一个卡片消息",
      "isNotificationOff" : false
    }
  },
  "coFeedOpenSpaceModel" : {
    "title" : "xxxx卡片"
  },
  "topOpenSpaceModel" : {
    "spaceType" : "ONE_BOX"
  }
}

添加动态数据源属性

在创建卡片的时候，可以配置卡片的动态数据源属性。下例创建了一个简单的具有动态数据源属性的卡片，动态数据源相关配置的参数为openDynamicDataConfig，详情参见动态数据源。

开放接口创建卡片实例

简介#

卡片数据#

动态数据源属性#

多场域属性#

步骤一：创建卡片#

步骤二：设置卡片的高级属性#

添加多场域属性#

添加动态数据源属性#