入门 - 云端

ManageEngine Endpoint Central 云端现支持使用 REST APIs 轻松集成您现有的基础设施。您可以通过单一控制台轻松执行各种桌面管理活动。您可以在侧边栏找到可用 API 的模块列表，如果需要更多 API，您可以 联系我们 并告知您的需求。

本文档描述了使用 API 的先决条件。

多个数据中心

Endpoint Central 云端托管于多个数据中心，因此可通过不同的域名访问。 Endpoint Central 云端 API 有 7 个不同的域名，您可以使用适用于您的域名。

此页面上的 APIs 适用于托管于 .com 域的组织。如果您的组织位于其他域， 请在使用 API 端点前将 “.com” 替换为相应的域名。

注意： 您可以在访问 Endpoint Central 时查看 URL 来确定您正在访问的域名。

认证

Endpoint Central REST API 支持 OAuth 2.0 协议，用于授权和认证 API 调用。请按照此处列出的步骤在 Endpoint Central APIs 中使用 OAuth 2.0 协议。

OAuth 令牌生成

生成 OAuth 令牌的步骤如下：

1. 1. 生成 <Client ID> 和 <Client Secret>
2. 2. 通过生成 <grant token>
3. 进行授权 3. 生成 和 <Access>
4. <Refresh Token> 4. 生成 <Access Token> <Access>

第 1 步：生成 Client ID 和 Client Secret

1. 1. 通过访问 developer console :
2. 将您的应用程序注册为新客户端。 2. 选择 <Client Type>

1. 适合您的应用类型。 3. 选择客户端类型后，填写所需信息并点击.

“创建” 注册成功后，您将获得一组 OAuth 2.0 凭证，如 和 <Client_ID> <Client_Secret>，仅 Zoho 和您的应用程序知晓。（请勿在任何地方泄露此凭证）

第 2 步：通过生成授权码进行授权

生成 注册成功后，您将获得一组 OAuth 2.0 凭证，如 和 <Client_ID><grant token> 后，需生成授权码。根据客户端类型，有两种生成方式。

1. i. 自助客户端方法 - 适用于自助客户端类型。
2. ii. 重定向方法 - 适用于基于服务器的应用程序。

自助客户端方法

• - 注册后，点击应用列表中的 <Self Client> 方法。
• - 输入有效的 <scope>。 （详细信息请参见 Scopes ）
• - 选择时间期限。

注意：本步骤生成的授权<Code> 将在所选期限后过期。 <Access>(第 3 步） 需在授权码过期前生成。

• - 输入 <Scope> 描述。

• 点击 创建 以生成 < code>

重定向方法（适用于基于服务器的应用程序）

通过以下 URI 发送请求并附带参数

https://<ZohoAccounts_Server_URI>/oauth/v2/auth?scope=<SCOPE>&client_id=<CLIENT_ID>&state=testing&response_type=code&redirect_uri=<REDIRECT_URI>&access_type=offline&prompt=consent

注意：带*的字段为必填项

示例

https://accounts.zoho.com/oauth/v2/auth?scope=DesktopCentralCloud.Common.READ&client_id=1000.I******************YF&state=54************5&response_type=code&redirect_uri=https://zylkerapps.com/oauth2callback&access_type=offline&prompt=consent

调用此请求时，如果您已登录Zoho，则会显示用户同意页面；如果您没有有效的Zoho登录会话，则会重定向到Zoho登录页面，需要输入Zoho凭据登录。身份验证后将显示用户同意页面。

• 1. 点击 “接受”，应用程序被授权。授权 Response_type* 作为参数发送到redirect_uri。
• 2. 您的后端脚本需要从上述URL存储以下详细信息。
•   code={grant_token} - 用于生成访问令牌和刷新令牌。
•   location={domain} - 告诉您用户的域名，您需要从该域调用API。
•   accounts-server={accounts_URL} - 这是您的accounts URL，用于生成刷新令牌和访问令牌。

注意： 此 code 仅在60秒内有效。下一步必须在此时间内完成。

当用户点击 “拒绝”时，浏览器将带有参数error=access_denied重定向到重定向URI，您的应用程序将被拒绝访问Endpoint central中的用户数据。

第3步：生成访问令牌和刷新令牌

访问令牌

访问令牌发送到资源服务器以访问用户的受保护资源。 <Access token> 提供对Endpoint central API的安全且临时访问，应用程序通过它向连接的应用发出请求。每个 <access token> 仅在一个小时内有效，并且只能用于作用域中描述的操作集合。

刷新令牌

刷新令牌用于获取新的 <access tokens>。该令牌拥有 无限的生命周期，直到终端用户撤销。.

生成 授权码，需要对以下URI发出POST请求，携带如下参数，以生成 <refresh_token> 和 <access_type>.

方法：POST

https://<ZohoAccounts_Server_URI>/oauth/v2/token?code=<CODE>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&redirect_uri=<REDIRECT_URI>&grant_type=authorization_code

注意：带*的字段为必填项

示例

方法： POST

https://accounts.zoho.com/oauth/v2/token?code=1000*********************e95e&client_id=1000.I*****************6YF&client_secret=1b****************96&redirect_uri=https://zylkerapps.com/oauth2callback&grant_type=authorization_code

• 响应中，您将获得 <access_type> 和 <refresh_token>.
• 
• 1. <access_type> 将在一个小时后过期。
• 2. <refresh_token> 是永久有效的，用于在当前访问令牌过期后重新生成新的 <access_type>。

注意： 每次 重新同意页面被接受时，会生成新的 <refresh token> 。每个用户最多允许20个 <refresh tokens> 。如果超出此限制，最早的 <refresh token> 会被自动删除以容纳最新的刷新令牌。无论第一个刷新令牌是否正在使用，均如此。

第4步：从刷新令牌生成访问令牌

<access_tokens> 有限的有效期，其在一小时后过期。令牌 <access_type> 过期后，用户或应用程序必须使用 <refresh_token> 来请求新的 <access_type>。使用过期的访问令牌将抛出“Invalid Oauthtoken”错误。

您可以在生成访问令牌时请求同时生成刷新令牌。要请求刷新令牌，请在生成授权令牌的请求中添加 access_type=offline （参见第2步）。

参数 <refresh_token> 始终通过以下参数生成： prompt=consent

注意： 使用 <refresh_token> 客户端在十分钟内最多可创建 十个访问令牌。如果达到限制， 其余十分钟内访问令牌的创建将被阻止。

通过以下POST URI及参数，可以生成新的 <access_type>.

方法：POST

https://<ZohoAccounts_Server_URI>/oauth/v2/token?refresh_token=<REFRESH_TOKEN>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&redirect_uri=<REDIRECT_URI>&grant_type=refresh_token

示例

方法： POST

https://accounts.zoho.com/oauth/v2/token?refresh_token=1000.1*********************fb8&client_id=1000.I**********************6YF&client_secret=1b******************************96&redirect_uri=https://zylkerapps.com/oauth2callback&grant_type=refresh_token

响应中，您将获得新的 <access_type>

使用OAUTH认证调用API

API - URI结构

所有API URI必须遵循以下格式。

<EndpointCentral_Server_URI>/api/{Version}/{Entity}/{Operation|Action}

<access_type> 只能在请求头中传递，不能作为请求参数传递。

• 头部名称 = Authorization
• 头部值> = Zoho-oauthtoken<空格><access_token>
• 示例： Authorization: Zoho-oauthtoken 1000.abcde12345fgh678.ijk9

在postman中调用SOM汇总API示例

请求URI： https://endpointcentral.manageengine.com

API URI： api/1.4/som/summary

方法： GET

作用域