从简介开始
Profiles API允许您跨应用程序和系统创建单个客户视图。API概要文件不是传统意义上的全面用户概要文件。相反,API配置文件就像不同外部应用程序中某人的姓名标签。这些信息可以让你将来自不同应用程序的数据流关联到Zendesk中的单个用户。亚博
概要文件由应用程序中某个人的一个或多个标识符组成,以及关于应用程序中所使用的人的一些可选属性。每个配置文件都与一个Zendesk用户相关联。亚博如果此人不是Zendesk用户,Profile亚博s API在创建其第一个配置文件时为此人创建Zendesk用户记录。
您可以使用概要文件来打破数据竖井。例如,您可以使用带有Events API的配置文件将公司系统中的事件与Zendesk Support中代理试图帮助的人员关联起来。亚博因为配置文件还包含客户的Zendesk用户id,所以可以将用户的票据、评论和其他Zendesk交互信亚博息拉到公司的系统中。
免责声明: 亚博Zendesk提供本文仅用于教学目的。亚博Zendesk不支持或保证该代码。亚博Zendesk也不能提供第三方技术的支持,比如curl。
需求
在Zende亚博sk Suite计划中获取Zendesk Support帐户。它将自动启用以使用API。
你可以报名14天的试用帐户。如果您有兴趣成为Zendesk开发人员合作伙伴,您可以将您的试用帐户转亚博换为赞助Zendesk支亚博持帐户.
您还需要帐户中的代理或管理权限才能使用API。
用户故事
你为一家虚构的公司Acme工作。该公司使用Zendesk Supp亚博ort进行客户服务,您的团队的任务是为其代理商构建Zendesk应用程序。你会得到下面的故事:
作为Support代理,我希望在Support中提交票据之前看到客户在Acme系统中采取的操作。
您决定使用Events API将Acme系统事件发送到Zendesk。亚博因为事件起源于Acme系统,所以每个事件都将与客户的Acme标识符相关联,例如电子邮件地址。问题是,您不能将Acme事件与Support中的用户关联起来,除非您可以将Support中的用户与Acme标识符关联起来。
解决方案是在Support中为用户创建一个配置文件,其中包含用户的Acme标识符。创建概要文件之后,您将能够将Acme系统中的事件与代理试图在Support中帮助的用户关联起来。
创建概要文件
概要文件通常是作为跟踪用户事件使用事件API。事件跟踪API期望每个事件都有一个概要对象。但是,您也可以使用profiles API主动创建概要文件。
您决定为每个新的Acme客户创建一个概要文件。每个概要文件将包含客户的至少一个Acme标识符。
使用以下端点创建概要文件:
把/ api / v2 / user_profiles吗?标识符={identifier_query}
请求体采用配置文件
对象的JSON格式:
{
“配置文件”:{
“源”:“极致”,
“类型”:“客户”,
“标识符”:[
{
“类型”:“电子邮件”,
“价值”:"(电子邮件保护)"
},
...
],
“属性”:{
“my_property_name”:“some_value”,
...
}
}
}
API路径包含标识符
参数,该参数接受标识符的查询.例子:
标识符= acme:顾客:电子邮件:(电子邮件保护)
您必须在所有PUT请求中包含标识符查询,包括用于创建概要文件的请求。在创建概要文件时,标识符查询扮演两个角色。
首先,它定义源而且类型你的新档案。在本例中,配置文件的源
是"acme"和它的类型
“客户”。
其次,标识符查询可以防止重复数据。标识符查询搜索与您试图创建的概要文件具有相同的源-类型-标识符组合的概要文件。如果找到了匹配的组合,API就用您的配置文件替换现有的配置文件。如果没有,则创建一个概要文件。
在配置文件中没有包含Zendesk用户i亚博d。的标识符中列出的标识符,如果API在Zendesk中发亚博现该用户标识符
数组,它会自动将新配置文件与该用户关联。如果API无法找到共享任何标识符的Zendesk亚博用户,它将创建一个与概要名称相同的匿名Zendesk用户,并将概要与该用户关联。
为了自动将概要文件与现有Zendesk用户关联,API尝试将概要文件中的下列标识符类型与相应的标识符类型匹配亚博用户标识类型在Ze亚博ndesk中:“email”,“facebook”,“phone_number”,“sdk”和“twitter”。这些被称为标准标识符类型.例如,要让API查找匹配,请确保指定类型
配置文件中的电子邮件标识符为“email”,而不是“e-mail”或“email_address”。
自己试试吧
要创建一个概要文件
从用户管理系统获取用户标识符。
假设Acme系统为用户返回以下用户数据:
“电子邮件”:“(电子邮件保护)"
“电话”:16505556789
“contact_preference”:“电子邮件”
“year_joined”:2017
将标识符数据传输到一个JSON对象,该对象具有以下格式:
{
“配置文件”:{
“源”:“极致”,
“类型”:“客户”,
“标识符”:[
{
“类型”:“电子邮件”,
“价值”:"(电子邮件保护)"
},
{
“类型”:“phone_number”,
“价值”:“16505556789”
}
],
“属性”:{
“contact_pref”:“电子邮件”,
“加入”:“2017”
}
}
}
请注意: API不接受数值。所有数字必须为字符串。例如:“16505556789”。
属性中的属性名
属性
对象可以是你喜欢的任何东西。将JSON对象保存在一个名为profile.json.
在命令行界面中,导航到包含profile.json.
将以下curl命令粘贴到命令行界面并按Enter。
旋度“https://{子域名}.zendes亚博k.com/api/v2/user_profiles ?标识符= acme:顾客:电子邮件:(电子邮件保护)"\
-d @profile.json \
-H“application / json内容类型:\
-v-u{email_address}:{密码}-X把
确保将占位符值替换为您自己的。还要确保URL用引号括起来。
Windows用户:在这个例子和其他例子中,用插入号(\^)字符替换连续行反斜杠(\)。
示例响应
状态:201创建
{
“配置文件”:{
“id”:“03 f3sw90dxzp8ny7abg6fys9a9”,
“user_id”:“415233562812”,
“源”:“极致”,
“类型”:“客户”,
“名称”:"(电子邮件保护)",
“属性”:{
“contact_pref”:“电子邮件”,
“加入”:“2017”
},
“标识符”:[
{
“类型”:“电子邮件”,
“价值”:"(电子邮件保护)"
},
{
“类型”:“phone_number”,
“价值”:“16505556789”
}
],
“created_at”:“2021 - 04 - 21 - t06:01:02z”,
“updated_at”:“2021 - 04 - 21 - t06:26:12z”
}
}
如果Zen亚博desk用户收到"(电子邮件保护)或者电话号码“16505556789”在您的帐户中不存在,则创建一个新的Zendesk用户,并且配置文件与该用户相关联。亚博如果用户具有这些身份中的任何一个,则配置文件将与该用户关联。
由于请求中没有提供概要文件名称,因此根据概要文件命名规则使用标识符类型的值。电子邮件标识符类型为“(电子邮件保护)设置为配置文件名称。参见标准标识符获取更多信息。
如果概要文件中的任何标准标识符没有出现在Zendesk用户记录中,则标识符将作为Zendesk用户标识添加到记录中。亚博概要记录保持独立且不受影响。
获取个人资料
在为客户创建概要文件之后,您可以使用它在Acme系统中检索由该客户触发的事件。
通过在以下端点中指定概要文件的id来检索事件:
GET / api / v2 / user_profiles / {profile_id} /事件
第一步是通过客户的配置文件获取配置文件的id。您不需要知道客户在Zendesk中使用的标识符来获取概要文件。亚博您可以使用客户在Acme系统中使用的标识符。属性指定标识符标识符的查询.
Acme系统中无名女尸的一个标识符是电子邮件地址(电子邮件保护)”。因此,您的标识符查询可以如下所示:
acme:顾客:电子邮件:(电子邮件保护)
自己试试吧
来获取档案
将以下curl命令粘贴到命令行界面并按Enter。
旋度“https://{子域名}.zendes亚博k.com/api/v2/user_profiles ?标识符= acme:顾客:电子邮件:(电子邮件保护)"\
-v-u{email_address}:{密码}
确保将占位符值替换为您自己的。
示例响应
状态:200好吧
{
“配置文件”:{
“id”:“03 f3sw90dxzp8ny7abg6fys9a9”,
“user_id”:“415233562812”,
“源”:“极致”,
“类型”:“客户”,
“名称”:"(电子邮件保护)",
“属性”:{
“contact_pref”:“电子邮件”,
“加入”:“2017”
},
“标识符”:[
{
“类型”:“phone_number”,
“价值”:“16505556789”
},
{
“类型”:“电子邮件”,
“价值”:"(电子邮件保护)"
}
],
“created_at”:“2021 - 04 - 21 - t06:41:25z”,
“updated_at”:“2021 - 04 - 21 - t06:41:25z”
}
}
然后可以使用概要文件id (“id”:“01 bx5zzkbkactav9wevgemmvry”
)在Acme系统中获取由客户触发的事件。例子:
旋度https://{子域名}.亚博.com/api/v2/user_profiles/01BX5ZZKBKACTAV9WEVGEMMVRY/事件\
-H“接受:application / json”\
-v-u{email_address}:{密码}
有关更多信息,请参见事件API参考文档。
在Ze亚博ndesk应用程序中,您可以获取用户对象的配置文件,例如票据请求者。看到在Zendesk应用程序中访问配置文件亚博.
更新配置文件
你可以用PATCH请求修改一个现有的配置文件:
补丁/ api / v2 / user_profiles吗?标识符={identifier_query}
端点使用标识符查询来选择要更新的概要文件。
自己试试吧
无名氏最近给了Acme一个办公室电话号码。您要将电话号码添加到她的Acme配置文件中。
在JSON对象中指定附加的办公室电话号码,格式如下:
{
“配置文件”:{
“标识符”:[
{
“类型”:“office_phone”,
“价值”:“16505554387”
}
]
}
}
将JSON对象保存在一个名为patch.json.
在命令行中运行PATCH请求:
旋度“https://{子域名}.zendes亚博k.com/api/v2/user_profiles ?标识符= acme:顾客:电子邮件:(电子邮件保护)"\
-d @patch.json \
-H“application / json内容类型:\
-v-u{email_address}:{密码}-X补丁
确保将占位符值替换为您自己的。
示例响应
状态:200好吧
{
“配置文件”:{
“id”:“03 f3sw90dxzp8ny7abg6fys9a9”,
“user_id”:“415233562812”,
“源”:“极致”,
“类型”:“客户”,
“名称”:"(电子邮件保护)",
“属性”:{
“contact_pref”:“电子邮件”,
“加入”:“2017”
},
“标识符”:[
{
“类型”:“phone_number”,
“价值”:“16505556789”
},
{
“类型”:“电子邮件”,
“价值”:"(电子邮件保护)"
},
{
“类型”:""office_phone”,
“价值”:“16505554387”
}
],
“created_at”:“2021 - 04 - 21 - t06:41:25z”,
“updated_at”:“2021 - 04 - 21 - t06:41:25z”
}
}
如果要更改标识符而不是添加标识符,则必须替换配置文件。首先对概要文件发出GET请求,修改标识符
对象,然后使用修改后的概要文件发出PUT请求。
如果您通过概要id获取用户的事件,请记住概要id将会更改。
下一个步骤
您为虚构的客户创建了一个概要文件,然后使用它来列出客户在Acme中触发的事件。您还更新了一位客户的个人资料。
继续试验API。编写一个连接到用户管理系统的小脚本,并使用概要文件获取Zendesk中的客户票据列表。亚博
如果您正在构建Zendesk应用程序,您可亚博以获取与用户对象(如票据请求者)关联的事件。看到访问Zendesk应用程序中的事件亚博.
有关参考文档,请参见概要文件的API.