API设置

AD360 REST API有助于AD360与任何第三方应用程序或Web服务之间的数据共享；它们使您可以管理AD360中可用的各种设置，例如域设置，代理服务器设置和电子邮件服务器设置。可以从能够发出HTTP请求的任何应用程序中利用这些API。

可用的API

以下列表包含当前可用的AD360 API及其功能：

API 功能
获取域设置 阅读AD360中配置的域的详细信息。
更新域凭证 添加/修改在AD360中配置的域凭据。
获取代理设置 阅读AD360中配置的代理服务器设置。
更新代理设置 添加/修改AD360中配置的代理服务器设置。
获取邮件服务器设置 阅读AD360中配置的邮件服务器设置。
更新邮件服务器设置 添加/修改在AD360中配置的邮件服务器设置。

注意: 仅支持JSON请求（内容类型：application / x-www-form-urlencoded）和响应（内容类型：application / json）。

如何访问AD360的API？

要访问AD360的API，首先需要创建一个AuthToken。请按照以下步骤操作：

  1. 以管理员身份登录到AD360。
  2. 转到管理 → 常规设置→ API设置.

    ad360-api-settings

  3. 单击创建新的身份验证令牌.
  4. 通过单击+符号选择要访问的范围 。

    什么是范围？
    范围定义了可以使用AuthToken访问哪些API。一个或一组API可以是作用域的一部分。

  5. 接下来，选择身份验证令牌的 到期日期.
  6. 点击创建.

    create-auth-token

  7. 您的身份验证令牌将被创建。

    注意:复制此AuthToken并确保其安全以备将来使用。如果丢失，则无法检索，必须重新生成。

API使用

要访问AD360 API，请使用以下URL格式：

<scheme:port[/context]>/RestAPI/*.*[?query][#fragment]

示例: http://ad360-server:8082/RestAPI/DomainSettings/getDomains

授权: Bearer <authtoken>

管理身份验证令牌

您可以在AD360的“ API设置”页面下找到已创建的所有AuthToken。从这里，您可以看到AuthToken的各种详细信息，例如它们的到期日期，范围，创建日期和上次访问时间。您也可以撤消AuthToken以完全禁用它。请按照以下步骤管理AuthToken：

  1. 以管理员身份登录到AD360。
  2. 转到管理 → 常规设置 → API 设置. 您将看到一个包含所有已创建的身份验证令牌的表。
  3. 要过滤身份验证令牌请执行以下操作：: 从显示下拉列表中, 您可以选择是查看所有身份验证令牌还是仅查看活动，过期或已撤销的身份验证令牌。
  4. 要查看份验证令牌的范围，请执行以下操作：: 单击Scope列 下的以查看身份验证令牌提供访问权限的所有范围。
  5. 审核身份验证令牌访问：: 将鼠标悬停在“上次访问时间”的值上. 审核图标将出现。单击它以查看谁访问身份验证令牌的详细审核跟踪。
  6. 撤消身份验证令牌: 将鼠标悬停在上次访问时间列旁边的空白处。出现“撤销”链接。单击它以撤消身份验证令牌。

    7. 注意:  撤销身份验证令牌后，依赖于它的API将不再起作用。

获取域设置API

使用此API，您可以获取在AD360中配置的域的详细信息。

  • 请求 URL: http://<ad360-server>: <port>/RestAPI/DomainSettings/getDomains
  • HTTP方法: GET
  • 授权: Bearer <authtoken>
  • 请求参数:
    参数 强制性 描述
    零 - 无需参数
  • 响应参数:
    参数 强制性 描述
    DEFAULT_NAMING_CONTEXT 是 表示域的默认命名上下文。
    IS_DEFAULT_DOMAIN 是 表示该域是否在登录页面中用作默认域。
    DC_LIST 是 列出域的域控制器。
    DOMAIN_FLAT_NAME 是 显示域的域名平面名称。
    DOMAIN_NAME 是 显示域名。
    DOMAIN_DNS_NAME 是 显示域的DNS名称。
    USER_NAME No 显示用于在AD360中配置域的帐户的用户名。
    DOMAIN_FUNCTIONAL_LEVEL 是 显示域的域功能级别。
    IS_AUTHENTICATION_REQUIRED 否 表示在配置域时是否提供了身份验证详细信息。
    IS_LDAP_SSL_ENABLED 否 表示域和AD360之间的连接是否已启用LDAPS。
    STATUS_MESSAGE 否 显示前一个域配置操作的结果。

示例请求:

http://ad360-dc1:8082/RestAPI/DomainSettings/getDomains

授权: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

回复示例：

[{"DEFAULT_NAMING_CONTEXT":"DC=ad360,DC=local","IS_DEFAULT_DOMAIN":"true","DC_LIST":["win2k12master.ad360.local","EST-ADC.ad360.local"],"DOMAIN_FLAT_NAME":"AD360","DOMAIN_NAME":"ad360.local","DOMAIN_DNS_NAME":"ad360.local","DOMAIN_FUNCTIONAL_LEVEL":"Windows Server 2008"}]

更新域设置API

使用此API，您可以更新AD360中的域设置。

  • 请求网址：: http://<ad360-server>:<port>/RestAPI/DomainSettings/updateDomainCredential
  • HTTP方法: POST
  • 授权: Bearer <authtoken>
  • 请求参数:
    参数 强制性 描述
    域名 是 必须具有以下属性（键值对）的JSON输入
    属性 强制性 描述
    域名 是 代表域名。
    用户名 否 用于验证的有效用户名。
    用户密码 否 用于身份验证的有效密码。
  • 响应参数：
    参数 强制性 描述
    状态 是 显示总体请求的状态（例如成功或失败）。
    域名 是 显示每个域的请求状态。

示例请求：

http://ad360-dc1:8082/RestAPI/DomainSettings/updateDomainCredential

授权: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

DOMAINS=[{"DOMAIN_NAME":"ad360.local","USER_NAME":"admin","USER_PASSWORD":"Test123"}]

回复示例:

{"STATUS":"SUCCESS","DOMAINS":{"ad360.local":"{\"DOMAIN_STATUS\":\"SUCCESS\"}"}}

  • 错误回应:
    无效的域 示例:{"STATUS":"SUCCESS","DOMAINS":{"--":"{\"DOMAIN_STATUS\":\"FAILURE\",\"ERROR_MSG\":\"INVALID_DOMAIN\"}"}}
    域不可用 示例:{"STATUS":"SUCCESS","DOMAINS":{"ad360.local":"{\"DOMAIN_STATUS\":\"FAILURE\",\"ERROR_MSG\":\"INVALID_OR_INSUFFICIENT_CREDENTIAL\"}"}}
    INVALID_OR_INSUFFICIENT_CREDENTIAL
    服务器故障 示例:{"STATUS":"SUCCESS","DOMAINS":{"ad360.local":"{\"DOMAIN_STATUS\":\"FAILURE\",\"ERROR_MSG\":\"FAILURE_IN_SERVER\"}"}}

    {"STATUS":"FAILURE","ERROR_MSG":"FAILURE_IN_SERVER"}

获取代理设置API

使用此API，您可以获取AD360中配置的代理服务器的详细信息。

  • 请求网址: http://<ad360-server>:<port>/RestAPI/ProxySettings/getSettings
  • HTTP方法: GET
  • 授权: Bearer <authtoken>
  • 请求参数:
    参数 强制性 描述
    零 无需参数。
  • 响应参数:
    参数 强制性 描述
    启用代理 是 启用或禁用代理服务器。
    服务器名称 否 代理服务器的主机名或IP地址。
    端口 否 代理服务器的端口号。
    用户名 否 用于代理服务器身份验证的用户名。

示例请求:

http://ad360-dc1:8082/RestAPI/ProxySettings/getSettings

授权: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

回复示例:

{"ENABLE_PROXY":"true","SERVER_NAME":"ad360-dc1","PORT":"5005","USER_NAME":"admin"}

更新代理设置API

使用此API，您可以更新AD360中的代理设置。

  • R请求URL: http://<ad360-server>:<port>/RestAPI/ProxySettings/updateSettings
  • HTTP方法: POST
  • 授权: Bearer <authtoken>
  • 请求参数:
    参数 强制性 描述
    代理设置 是 必须具有以下属性（键值对）的JSON输入。
    属性 强制性 描述
    启用代理 是 启用或禁用代理服务器。
    服务器名称 是 代理服务器的服务器名称或IP地址。
    端口 是 启用或禁用代理服务器.
    用户名 否 用于代理服务器身份验证的用户名。
    PASSWORD 否 用于代理服务器身份验证的密码。
  • 响应参数:
    参数 强制性 描述
    状态 是 显示请求的状态（例如成功或失败）。

示例请求：

http://ad360-dc1:8082/RestAPI/ProxySettings/updateSettings

授权: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

PROXY_SETTINGS={"ENABLE_PROXY":"true","SERVER_NAME":"ad360-dc1","PORT":"5005","USER_NAME":"admin","PASSWORD":"Test123"}

回复示例:

{"STATUS": "SUCCESS"}

  • 错误回应:

    PS001 - 访问代理服务器所需的身份验证。

    PS002 - 代理服务器已关闭。请稍后再试。

    PS003 - 无法保存代理设置。

获取邮件设置API

使用此API，您可以获得在AD360中配置的邮件服务器的详细信息。

  • 要求网址: http://<ad360-server>:<port>/RestAPI/MailSettings/getSettings
  • HTTP 方法: GET
  • 授权: Bearer <authtoken>
  • 请求参数:
    参数 强制性 描述
    零 - 无需参数
  • 响应参数:
    参数 强制性 描述
    服务器名称 是 代表邮件服务器的主机名或IP地址。
    端口 是 邮件服务器的端口号
    邮件发件人ID 是 表示用于发送通知电子邮件的电子邮件地址
    邮件管理ID 是 表示将通知电子邮件发送到的电子邮件地址的逗号分隔列表。
    用户名 否 用于邮件服务器身份验证的用户名.
    连接安全性 是 表示安全连接类型（SSL或TLS）

示例请求：

http://ad360-dc1:8082/RestAPI/MailSettings/getSettings

授权: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

回复示例:

{"PORT":"25","FROM_MAIL_ID":"no-reply@ad360.local","SERVER_NAME":"smtp","USER_NAME":"admin","ADMIN_MAIL_ID":"admin@ad360.local,super-admin@ad360.local"}

更新邮件设置API

使用此API，您可以更新AD360中的邮件服务器设置。

  • 请求网址: http://<ad360-server>:<PORT>/RestAPI/MailSettings/updateSettings
  • HTTP 方法: POST
  • 授权: Bearer <authtoken>
  • 请求参数:
    参数 强制性 描述
    邮件设置 是 必须具有以下属性（键值对）的JSON输入
    属性 强制性 描述
    服务器名称 是 邮件服务器的服务器名称或IP地址。
    端口 是 邮件服务器的端口号
    发件人ID 是 从中发送通知的电子邮件地址。
    收件人ID 是 收件人列表。
    用户名 否 用于邮件服务器身份验证的用户名。
    密码 否 用于邮件服务器身份验证的密码。
    连接安全性 是 可接受的值为SSL或TLS。
  • Response Parameters:
    参数 强制性 描述
    STATUS 是 Shows the status of the request (e.g. success or failure).

示例请求:

http://ad360-dc1:8082/RestAPI/MailSettings/updateSettings

授权: Bearer ztfhotq5ytctmgy4zi00nzk2lwjiodkmtwvlymvjyja3yjm5

MAIL_SETTINGS={"PORT":"25","FROM_MAIL_ID":"no-reply@ad360.local","SERVER_NAME":"smtp","USER_NAME":"admin","ADMIN_MAIL_ID":"admin@ad360.local","PASSWORD":"Test123"}

回复示例:

{"STATUS": "SUCCESS"}

  • 错误回应:

    MS001 - 无效的电子邮件地址

    MS002 - 无效的管理员电子邮件地址。

    MS003 - 无效的电子邮件地址，或邮件服务器需要身份验证。

    MS004 - 请检查服务器名称/ IP，端口号和连接类型是否正确，然后重试。

    MS005 - 网络故障，或邮件服务器已关闭。

    MS006 - 邮件服务器的身份验证详细信息不正确。

    MS007 - 无法识别的SSL消息：启用了安全连接。

    MS008 - 无效的域名。

    MS009 - 请确保邮件地址不包含“zohocorp”域。

    MS010 - 无效的服务器名称或端口号。

    MS011 - 无效的用户名或密码。

    MS012 - 无法配置启用了TLS的SMTP服务器。

    MS013 - 无效的连接类型。连接类型应为SSL或TLS。

    MS014 - 无效的端口号。

常见错误响应代码

AT001 - 无效或缺少AuthToken。检查AuthToken是否未吊销或过期。
AT002 - 给定的AuthToken没有访问所请求API的必要权限。
AT003 - 请求的API不支持此HTTP方法。
AT004 - 访问被拒绝。用户角色已更改，并且用户不再具有访问此API的权限。
AT005 - 访问被拒绝。您无权访问此API。请与您的管理员联系。
CE001 - 无效或缺少必需参数。
CE002 - 出问题了。
CE003 - 无效的用户名或密码。

版权所有 © 2020, ZOHO Corp.保留所有权利