BEMS 联系服务 API 参考用户指南

端点： :8443/api/联系方式
从 BEMS 中的邮箱检索联系人信息的 HTTP 请求的格式为：
邮政:8443/api/联系方式

在 BEMS 中的邮箱中创建联系人的 HTTP 请求的格式为：
邮政：8443/api/联系人/创建

更新 BEMS 中邮箱中的联系人的 HTTP 请求的格式为：
邮政：8443/api/联系人/更新

用于在联系人文件夹下创建其他文件夹和子文件夹的 HTTP 请求的格式
BEMS中的邮箱是：
邮政:8443/api/文件夹/创建

获取BEMS中邮箱中的联系人文件夹下的所有文件夹和子文件夹的HTTP请求格式为：
邮政:8443/api/文件夹/获取

以下是amp头文件：
内容类型：application/json
X-Good-GD-AuthToken：
请求联系人列表信息
第三方 BlackBerry Dynamics 应用程序可以检索在您指定的时间段内添加的联系人信息、指定的联系人或用户邮箱中的联系人文件夹中的联系人列表。
检索联系人列表信息属性
下表描述了当您从邮箱中的用户文件夹检索联系人列表信息时可以包含在 JSON 格式的请求中的请求正文属性。

范围	类型	描述
帐户	细绳	该参数指定用户的电子邮件帐户，用于请求联系信息（例如amp乐，杰米01@ex365.example.com).
按名字	细绳	该参数指定根据特定名称搜索用户的本地联系人。搜索结果包括具有一组指定字符的所有联系人。例如ample, “ByName”: “Jane” 将返回以 Jane 作为名字、姓氏或名字的一部分的所有用户。使用此参数时，您还可以包含 UserShape 属性“Basic”或“Detail”以检索返回的联系人的附加信息。有关详细信息，请参阅下面的 UserShape 参数。
通过电子邮件	细绳	该参数指定搜索具有特定电子邮件地址的用户的本地联系人列表。使用此参数时，您还可以包含 UserShape 参数属性“Basic”或“Detail”以检索返回的联系人的附加信息。有关详细信息，请参阅下面的 UserShape 参数。
文件夹ID	细绳	此参数从指定的FolderId 检索联系人。这是可选的。如果未指定FolderId，BEMS将从用户的联系人文件夹中检索联系人。
最大数量	整数	此参数指定在搜索查询中返回的联系人或对象的最大数量。默认情况下，BEMS 一次最多只能返回 512 个项目。客户端必须多次调用才能检索超过通过设置“Offset”参数可实现 512 项。 “MoreAvailable”值告诉客户是否有更多商品可用。有关详细信息，请参阅下面的 API 响应表。
抵消	整数	该参数指定批量响应的起点。默认情况下，偏移量为 0（零）。
自从Ts	整数（长）	该参数指定自指定时间以来用户个人联系人列表中新增或修改的联系人。 sinceTs 以纪元时间格式指定。如果要检索新的和修改的联系人，则必须指定“SinceT”才能开始搜索联系人。如果未指定SinceTs，BEMS 将从用户的联系人文件夹中检索所有联系人。使用此参数时，您还可以包含 UserShape 参数属性“Basic”或“Detail”以检索返回的联系人的附加信息。有关详细信息，请参阅下面的 UserShape 参数。
用户形状	字符串数组	此参数指定要在搜索结果中返回的属性列表（例如amp文件、基本、手机、职位名称、照片）。 UserShape 支持预设的常用属性列表：Basic 和 Detail。可以在 BEMS 中配置基本和详细属性名称列表。 • 基本：默认情况下，此属性返回以下属性列表：LastName、DisplayName、EmailAddress 和 PhoneNumbers。 • 详细信息：默认情况下，除了基本属性之外，此属性还返回以下属性列表：PhyicalAddresses、CompanyName、JobTitle、Department 和 Photo。有关管理员如何进行操作的说明 view 或配置 UserShape 属性，请参阅附录：配置 UserShape 属性。

API 响应
下表描述了当您从用户的本地联系人列表检索联系人时，JSON 格式的 API 响应中可能出现的响应属性。

财产	类型	描述
更多可用	布尔值	此参数表示可用的联系人数量多于返回的响应数量。如果 MoreAvailable 为 true，则客户端继续调用 API，将“Offset”值更改为先前响应中收到的值。客户端执行此调用，直到 MoreAvailable 值为 false，这表示没有更多联系人可返回。
总数	整数	此参数指定与获取查询匹配的联系人总数。
下一页偏移量	整数或空值	该参数指定第二批返回的联系人的起始点。
尺寸	整数	此参数指定响应中返回的联系人数量，最多可达指定的 MaxNumber 大小。
抵消	整数	该参数指定批量响应的起点。
收藏	地图列表	该参数指定请求中返回的联系人列表。

请求联系方式

您可以从用户的主联系人文件夹和用户创建的子文件夹中检索联系人。
已删除的联系人不会被退回。如果客户端未在请求中提供FolderId，则会从主文件夹中检索联系人。
在接下来的几amp在该文件中，BEMS 从特定子文件夹中检索用户 Jamie01 的所有联系人，不包括任何已删除的联系人。 BEMS 的第一个响应最多包含 100 个联系人，由 MaxNumber 指定。检索到的每个联系人都包含 BEMS 中指定的默认基本属性。
如果可用联系人超过 100 个（例如amp文件中，此邮箱包含的 TotalCount 为 150 个联系人）响应包含 MoreAvailable 为 true，因此客户端应用程序使用 NextOffset 值发送其他请求以批量检索联系人，直到 MoreAvailable 为 false。在这个前amp文件中，基本属性返回联系人的以下信息：

显示名称
电子邮件
给定的名称
姓

在以下示例中amp文件中，客户端提供一个FolderId，BEMS 从特定文件夹中检索联系人。如果请求成功，BEMS返回符合查询条件的前100个联系人。 BEMS 还返回联系人的 TotalCount 和 NextPageOffset 以检索下一批联系人。客户端将 Offset 设置为与上一个查询的 NextPageOffset，以接收下一批。
BEMS 返回接下来的 50 个联系人，总共 150 个联系人。没有其他可用的联系人。使用电子邮件地址和预设属性请求联系人
您可以从用户的联系人文件夹或用户使用多个属性在邮箱中创建的文件夹和子文件夹中检索联系人（例如amp文件中，根据电子邮件地址检索用户并包含联系人的预设详细信息属性）。在这个前amp文件中，响应包含一个联系人，且 MoreAvailable 为 false。如果识别到的联系人超过 512 个，则响应指示 MoreAvailable 为 true，客户端会发送额外的请求来批量检索联系人，直到 MoreAvailable 为 false。如果客户端提供FolderId，BEMS将从特定文件夹中检索联系人。如果请求成功，BEMS 将返回以下响应，并且第三方 BlackBerry Dynamics 应用程序将显示电子邮件地址为 jane_doe@ex 的联系人的以下信息ample.com。如果属性不可用，BEMS 将返回空值，并且该信息不会包含在响应中。在这个前amp文件中，显示 Jane Doe 的以下信息：

显示名称
给定的名称
姓
全名
電子郵件地址

使用特定属性请求联系人列表信息
您可以请求返回特定属性的联系人的用户联系信息（例如ample，仅联系人的名字）。在接下来的几amp在该代码中，BEMS 请求用户联系人文件夹中所有联系人的名字。响应最多包含 50 个联系人。如果客户端提供FolderId，BEMS 会请求特定文件夹中的联系人。如果请求成功，BEMS 将返回以下响应，并且第三方 BlackBerry Dynamics 应用程序会显示联系人的名字。

创建并请求文件夹和子文件夹信息

第三方 BlackBerry Dynamics 应用程序可以检索用户在其联系人文件夹中创建的文件夹和子文件夹信息。还可以在特定文件夹中创建子文件夹。
创建和更新文件夹参数
下表描述了在用户邮箱的联系人文件夹中创建文件夹或子文件夹时可以包含在 JSON 格式请求中的请求正文属性。

范围	类型	描述
文件夹名称	细绳	该参数指定用户创建的文件夹或子文件夹的名称。
父文件夹ID	细绳	此参数在指定的 ParentFolderId 中创建联系人。这是可选的。如果未提供 ParentFolderId，BEMS 将在用户的联系人文件夹中创建联系人。

创建文件夹或子文件夹
您可以在用户的联系人文件夹中创建文件夹和子文件夹。 ParentFolderId 是可选的。如果未提供并且创建了文件夹，则该文件夹将显示在用户的联系人文件夹中。在接下来的几amp在文件代码中，名为“Supportfolder”的文件夹将作为指定 ParentFolderId 中的子文件夹创建。如果请求成功，BEMS 将返回 201 HTTP 响应代码，表明联系人文件夹已成功创建。
如果父文件夹中存在同名文件夹，BEMS 将返回 200 HTTP 响应代码，并且不会保存该文件夹。请求联系人文件夹下的所有文件夹和子文件夹
您可以检索用户在用户的联系人文件夹中创建的所有文件夹和子文件夹。在接下来的几amp通过文件代码，BEMS 检索用户创建的所有文件夹。如果请求成功，BEMS 将返回以下响应，并且第三方 BlackBerry Dynamics 应用程序将显示检索到的文件夹。

添加联系信息

第三方 BlackBerry Dynamics 应用程序可以在用户的联系人文件夹或用户在其邮箱中创建的文件夹和子文件夹中创建和更新联系人信息。
创建联系人时使用的属性
以下列表显示了在邮箱的用户文件夹中创建联系人时可以包含在 JSON 格式请求中的受支持正文属性。请求正文中任何为 null 或空的值都不会保存在联系人中。
如果用户正在更新现有联系人，则请求的所有值（无论是否更改）都会提交给 BEMS。创建联系人时可以指定以下值：

接触
• 名
• 中间名字
• 姓
• 手机
• 家庭电话
• 家庭电话2
• 家庭传真
• 其他传真
• 电子邮件地址1
• 电子邮件地址2
• 电子邮件地址3
• 商务电话
• 商务电话2
• 车载电话
• 公司主要电话
• 综合业务数字网
• 打回来
• 无线电话
• 常用电话
• 助理电话
• 电传
• TtyTdd电话

家庭地址
• 街道
• 城市
• 状态
•国家
• 邮政编码
工作
• 公司
• 职称
• 部门
• 办公室
• 经理
• 助手

营业地址
• 街道
• 城市
• 状态
•国家
• 邮政编码

使用特定属性创建联系人
您可以使用特定属性创建联系人。在接下来的几amp通过该代码，BEMS 在用户的联系人文件夹中创建联系人。如果包含 ParentFolderId，则会在指定文件夹中创建联系人。
在此例中amp文件中，用户使用以下联系人信息创建联系人：

名
姓
中间名字
手机
家庭电话
公司电话
电子邮件
公司名称

如果成功创建联系人，BEMS 将返回 uniqueId，并且第三方 BlackBerry Dynamics 应用程序将显示提供的联系人信息。如果未指定属性，BEMS 将返回空值，并且信息不会保存在联系人中。

更新联系人列表信息

您可以使用特定属性更新联系人的信息。在接下来的几amp通过该代码，BEMS 更新用户联系人文件夹中 NewContact Last 的联系信息。客户端发送要更新的联系人的 UniqueID。当更新联系人时，客户端会将该联系人的所有值发送到 BEMS，无论这些值是否已修改。如果客户端提供 ParentFolderID，BEMS 会更新指定文件夹中的联系人。
在此例中ample，联系人将更新其工作信息。新的和现有的信息被发送到 BEMS 进行更新。

职称
部门
中间名字
手机
家庭电话
公司电话
电子邮件
公司名称

如果请求成功，BEMS 将返回 200 HTTP 响应代码，表明联系人已成功更新。

附录：配置 UserShape 属性

警告： 除非需要更改，否则请勿修改 UserShape 属性。升级 BEMS 软件时，不会保留修改的设置。
可以为 UserShape 属性指定以下值。其他值将被忽略。

• 别名	• 用户证书
• 电子邮件地址	• 用户mime 证书
• 显示名称	• PrUserx509 证书
• 给定的名称	• 家庭电话
• 名	• 家庭电话2
• 姓	• 手机
• 姓	• 寻呼机
• 全名	• 商务电话
• 公司名称	• 商务传真
• 公司	• 其他电话
• 部门	• 电话号码
• 职称	• 物理地址
• 标题	• 经理
• 照片	• 直接报告

打开浏览器并转到 Apache Karaf Web 控制台配置 web网站位于 https:// :8443/system/console/configMgr 并使用适当的 Microsoft Active Directory 凭据以管理员身份登录。
在菜单上，单击 OSGi > 配置。
搜索然后单击“目录查找通用配置”。
basicPropertyNames 字段中列出了基本属性值。
单击 + 按钮和属性名称将公共属性添加到列表中，或单击 - 按钮从列表中删除公共属性。

在detailedPropertyNames字段中，列出了常见属性名称的详细属性值名称。
单击 + 按钮和属性将公共属性添加到列表中，或单击 – 按钮从列表中删除公共属性。
单击保存。

法律声明
©2023 BlackBerry Limited。商标，包括但不限于 BLACKBERRY、BBM、BES、EMBLEM Design、ATHOC、CYLANCE 和 SECUSMART，是 BlackBerry Limited、其子公司和/或附属公司的商标或注册商标，经许可使用，并明确保留此类商标的专有权。所有其他商标均为其各自所有者的财产。
专利，如适用，确定于： www.blackberry.com/patents.
本文件包括所有通过引用纳入的文件，例如在 BlackBerry 上提供或可获得的文档 webBlackBerry Limited 及其关联公司（“BlackBerry”）“按原样”和“可用”提供或访问的网站，无任何条件、背书、保证、陈述或保证，BlackBerry 不对任何印刷、本文档中的技术或其他不准确、错误或遗漏。为了保护 BlackBerry 的专有和机密信息和/或商业机密，本文档可能以通用术语描述 BlackBerry 技术的某些方面。 BlackBerry 保留定期更改本文档中包含的信息的权利；但是，BlackBerry 不承诺及时或根本不向您提供任何此类更改、更新、增强或对本文档的其他补充。本文档可能包含对第三方信息来源、硬件或软件、产品或服务的引用，包括组件和内容，例如受版权和/或第三方保护的内容 web网站（统称为“第三方产品和服务”）。BlackBerry 不控制任何第三方产品和服务，也不对其负责，包括但不限于第三方产品和服务的内容、准确性、版权合规性、兼容性、性能、可信度、合法性、体面性、链接或任何其他方面。本文档中包含对第三方产品和服务的引用并不意味着 BlackBerry 以任何方式认可第三方产品和服务或第三方。
除非您所在司法辖区的适用法律明确禁止，所有明示或暗示的条件、背书、保证、陈述或保证，包括但不限于任何关于耐用性、适合特定目的或用途、适销性、适销品质、非侵权性、令人满意的品质、所有权的条件、背书、保证、陈述或保证，或由法规、惯例、交易过程或贸易惯例引起的条件、背书、保证、陈述或保证，或与文档或其使用有关的 ...特此排除本文提及的任何软件、硬件、服务或任何第三方产品和服务。您可能还拥有其他权利，具体视州或省份而定。某些司法辖区可能不允许排除或限制默示保证和条件。在法律允许的范围内，任何与文档有关的默示保证或条件，在如上所述不能被排除但可以受到限制的范围内，特此限制为自您首次获得文档或索赔标的物之日起九十 (90) 天。
在您所在司法管辖区适用法律允许的最大范围内，在任何情况下，黑莓均不对与本文档或其使用、任何软件、硬件、服务或任何第三方的性能或不性能相关的任何类型的损害承担责任本文提及的产品和服务，包括但不限于以下任何损害：直接、后果性、惩戒性、附带、间接、特殊、惩罚性或严重损害、利润或收入损失损害、未能实现任何预期节省、商业投资溃烂，业务信息丢失、业务机会损失、数据损坏或丢失、传输或接收任何数据失败、与黑莓产品或服务结合使用的任何应用程序相关的问题、停机成本、无法使用黑莓产品或服务或其任何部分或任何通话服务、替代品成本、保险成本、设施或服务、资本成本或其他类似的金钱损失，无论此类损害是否是可预见或不可预见的，即使 BLACKBERRY 已发生被告知的可能性
此类损害。
在您所在司法辖区适用法律允许的最大范围内，BLACKBERRY 对您不承担任何其他合同、侵权或其他义务、责任或责任，包括任何疏忽责任或严格责任。
本文中的限制、排除和免责声明应适用于：（A）无论您提起的诉讼、要求或行动的原因性质如何，包括但不限于违反合同、疏忽、侵权、严格责任或任何其他法律理论，并且应在本协议的根本违反或违反或本协议中包含的任何补救措施的主要目的失败后继续存在；以及 (B) 向黑莓及其附属公司、他们的继任者、受让人、代理商、供应商（包括通话时间服务提供商）、授权黑莓经销商（也包括通话时间服务提供商）及其各自的董事、员工和独立承包商。
除了上述限制和排除之外，在任何情况下，黑莓的任何董事、员工、代理、分销商、供应商、独立承包商或黑莓的任何附属公司均不承担由本文档引起或与之相关的任何责任。在订阅、安装或使用任何第三方产品和服务之前，您有责任确保您的通话服务提供商已同意支持其所有功能。某些通话服务提供商可能不会通过订阅 BlackBerry Internet Service 提供 Internet 浏览功能。
请咨询您的服务提供商，了解可用性、漫游安排、服务计划和功能。安装第三方产品和服务或与 BlackBerry 产品和服务一起使用可能需要一项或多项专利、商标、版权或其他许可，以避免侵犯或违反第三方权利。您全权负责确定是否使用第三方产品和服务以及是否需要任何第三方许可。如果需要，您有责任获取它们。在获得所有必要的许可证之前，您不应安装或使用第三方产品和服务。与 BlackBerry 产品和服务一起提供的任何第三方产品和服务都是为了方便您而提供，并按“原样”提供，BlackBerry 和 BlackBerry 不提供任何明示或暗示的条件、认可、保证、陈述或保证对此不承担任何责任。您对第三方产品和服务的使用应受您同意与第三方签订的单独许可条款和其他适用协议的约束，但与 BlackBerry 的许可或其他协议明确涵盖的范围除外。
任何 BlackBerry 产品或服务的使用条款均在单独的许可或与 BlackBerry 签订的其他协议中规定。本文档中的任何内容均无意取代 BLACKBERRY 针对除本文档之外的任何 BLACKBERRY 产品或服务部分提供的任何明示书面协议或保证。
BlackBerry Enterprise Software 集成了某些第三方软件。与此软件相关的许可和版权信息可从以下网站获取： http://worldwide.blackberry.com/legal/thirdpartysoftware.jsp.

黑莓有限公司
大学大道东2200号
安大略省滑铁卢
加拿大 N2K 0A7
黑莓英国有限公司
一楼，皮尔斯大厦，西街，
伯克希尔梅登黑德 SL6 1RL
英国
加拿大出版

文件/资源

BEMS 联系服务 API 参考 [pdf] 用户指南
联系服务 API 参考、联系方式、服务 API 参考、API 参考、参考

参考

用户手册

什么是 BEMS 联系服务 API？

请求、创建和更新格式