OAuth 2.0

ManageEngine SerivceDesk Plus Cloud APIs 使用 OAuth 2.0 进行身份验证。本页面为您概述身份验证流程。有关 OAuth 2.0 流程、注册、令牌管理等详细信息，请参阅 Zoho OAuth 2.0 文档.

OAuth 2.0 工作原理

要访问 SerivceDesk Plus Cloud APIs，您的应用程序需要通过以下 OAuth 2.0 流程之一获取访问令牌。

高级步骤如下：

在 Zoho API 控制台注册您的应用程序。获取用户同意访问其数据并获得访问令牌。 
使用访问令牌调用 SerivceDesk Plus Cloud APIs。 
访问令牌会定期过期。过期时间以访问令牌响应中的

令牌过期

expires_in （秒）表示。为保持连续访问，您可以请求一个可选的刷新令牌，存储它，并根据需要使用它来生成新的访问令牌。 Zoho 支持不同应用类型（基于服务器、基于客户端、移动及桌面、有限输入设备和自客户端）的 OAuth 流程。您可以选择适合您应用程序的流程。

不同应用类型的不同 OAuth 流程

Zoho 在多个区域运营数据中心。如果您的应用程序服务于多个区域的用户，则必须在 API 控制台启用多数据中心支持，并针对 OAuth 及产品 API 调用使用特定区域的端点。

多数据中心支持

详见 OAuth 2.0 流程详解

ManageEngine ServiceDesk Plus Cloud APIs 使用选定的权限范围，控制客户端应用程序可以访问的资源类型。令牌通常包含多个权限范围，以确保安全性提升。

权限范围

例如，您可以生成权限范围以创建或查看服务请求，或查看元数据等。权限范围包含三个参数——服务名称、权限名称和操作类型。定义权限范围的格式为

例如：scope=SDPOnDemand.projects.ALL

scope=SDPOnDemand.scope_name.operation_type

其中，SDPOnDemand 是服务名称，projects 是权限名称，ALL 是操作类型。

可用权限范围列表 

组/模块权限范围提供用户对特定模块可执行的所有功能的完全访问权限。

例如，组权限可以允许用户读取、创建、更新和删除模块中的记录。

请求权限范围

操作类型

权限示例	描述	ALL
SDPOnDemand.requests.ALL	访问请求模块相关的所有 API	CREATE
SDPOnDemand.requests.CREATE	SDPOnDemand.requests.CREATE	创建 Requests 模块相关记录
读取	SDPOnDemand.requests.READ	读取 Requests 模块相关记录
更新	SDPOnDemand.requests.UPDATE	更新 Requests 模块相关记录
删除	SDPOnDemand.requests.DELETE	删除 Requests 模块相关记录

Problems 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.problems.ALL	访问 Problems 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.problems.CREATE	创建 Problems 模块相关记录
读取	SDPOnDemand.problems.READ	读取 Problems 模块相关记录
更新	SDPOnDemand.problems.UPDATE	更新 Problems 模块相关记录
删除	SDPOnDemand.problems.DELETE	删除 Problems 模块相关记录

Changes 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.changes.ALL	访问 Changes 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.changes.CREATE	创建 Changes 模块相关记录
读取	SDPOnDemand.changes.READ	读取 Changes 模块相关记录
更新	SDPOnDemand.changes.UPDATE	更新 Changes 模块相关记录
删除	SDPOnDemand.changes.DELETE	删除 Changes 模块相关记录

Projects 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.projects.ALL	访问 Projects 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.projects.CREATE	创建 Projects 模块相关记录
读取	SDPOnDemand.projects.READ	读取 Projects 模块相关记录
更新	SDPOnDemand.projects.UPDATE	更新 Projects 模块相关记录
删除	SDPOnDemand.projects.DELETE	删除 Projects 模块相关记录

Releases 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.releases.ALL	访问 Releases 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.releases.CREATE	创建 Releases 模块相关记录
读取	SDPOnDemand.releases.READ	读取 Releases 模块相关记录
更新	SDPOnDemand.releases.UPDATE	更新 Releases 模块相关记录
删除	SDPOnDemand.releases.DELETE	删除 Releases 模块相关记录

Assets 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.assets.ALL	访问 Asset 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.assets.CREATE	创建 Asset 模块相关记录
读取	SDPOnDemand.assets.READ	读取 Asset 模块相关记录
更新	SDPOnDemand.assets.UPDATE	更新 Asset 模块相关记录
删除	SDPOnDemand.assets.DELETE	删除 Asset 模块相关记录

CMDB 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.cmdb.ALL	访问 CMDB 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.cmdb.CREATE	创建 CMDB 模块相关记录
读取	SDPOnDemand.cmdb.READ	读取 CMDB 模块相关记录
更新	SDPOnDemand.cmdb.UPDATE	更新 CMDB 模块相关记录
删除	SDPOnDemand.cmdb.DELETE	删除 CMDB 模块相关记录

Contracts 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.contracts.ALL	访问 Contracts 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.contracts.CREATE	创建 Contracts 模块相关记录
读取	SDPOnDemand.contracts.READ	读取 Contracts 模块相关记录
更新	SDPOnDemand.contracts.UPDATE	更新 Contracts 模块相关记录
删除	SDPOnDemand.contracts.DELETE	删除 Contracts 模块相关记录

Purchases 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.purchases.ALL	访问 Purchases 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.purchases.CREATE	创建 Purchases 模块相关记录
读取	SDPOnDemand.purchases.READ	读取 Purchases 模块相关记录
更新	SDPOnDemand.purchases.UPDATE	更新 Purchases 模块相关记录
删除	SDPOnDemand.purchases.DELETE	删除 Purchases 模块相关记录

自定义模块作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.custommodule.ALL	访问自定义模块实例所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.custommodule.CREATE	创建自定义模块实例记录
读取	SDPOnDemand.custommodule.READ	读取自定义模块实例记录
更新	SDPOnDemand.custommodule.UPDATE	更新自定义模块实例记录
删除	SDPOnDemand.custommodule.DELETE	删除自定义模块实例记录

Solutions 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.solutions.ALL	访问 Solutions 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.solutions.CREATE	创建 Solutions 模块相关记录
读取	SDPOnDemand.solutions.READ	读取 Solutions 模块相关记录
更新	SDPOnDemand.solutions.UPDATE	更新 Solutions 模块相关记录
删除	SDPOnDemand.solutions.DELETE	删除 Solutions 模块相关记录

Setup 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.setup.ALL	访问 Admin 模块相关所有 API
SDPOnDemand.requests.CREATE	SDPOnDemand.setup.CREATE	创建 Admin 模块相关记录
读取	SDPOnDemand.setup.READ	读取 Admin 模块相关记录
更新	SDPOnDemand.setup.UPDATE	更新 Admin 模块相关记录
删除	SDPOnDemand.setup.DELETE	删除 Admin 模块相关记录

General 作用域

权限示例	描述	ALL
SDPOnDemand.requests.ALL	SDPOnDemand.general.ALL	访问所有 General API
SDPOnDemand.requests.CREATE	SDPOnDemand.general.CREATE	创建 General 记录
读取	SDPOnDemand.general.READ	读取 General 记录
更新	SDPOnDemand.general.UPDATE	更新 General 记录
删除	SDPOnDemand.general.DELETE	删除 General 记录

一个或多个作用域也可以在 scope 中以逗号分隔方式列出。

示例：

scope=SDPOnDemand.requests.ALL,SDPOnDemand.projects.READ,SDPOnDemand.setup.READ,SDPOnDemand.setup.CREATE

此处包含 Request、Project 和 Admin 模块。因此这将提供 Request 模块的完全访问权限，Project 模块的读取访问权限，以及 Admin 模块的读取和创建访问权限。

有关作用域格式的更多详细信息，请参见 OAuth 作用域.

使用访问令牌调用 API

要验证您的 API 调用，请在每个 API 请求的 Authorization 头中包含访问令牌。

支持的格式

Authorization: Zoho-oauthtoken <space> {access-token-value}

示例

curl -X GET “https://sdpondemand.manageengine.com/api/v3/requests” \

按数据中心划分的 API 端点

调用 API 时，必须使用与你的用户数据中心对应的基础 URL。正确的 URL 会在 api_domain 的访问令牌响应中返回。

数据中心	API 基础 URL
美国 (US)	https://sdpondemand.manageengine.com （获取请求列表示例为： https://sdpondemand.manageengine.com/api/v3/requests)
欧盟 (EU)	https://sdpondemand.manageengine.eu （获取请求列表示例为： https://sdpondemand.manageengine.eu/api/v3/requests)
印度 (IN)	https://sdpondemand.manageengine.in （获取请求列表示例为： https://sdpondemand.manageengine.in/api/v3/requests)
澳大利亚 (AU)	https://servicedeskplus.net.au （获取请求列表示例为： https://servicedeskplus.net.au/api/v3/requests)
日本 (JP)	https://servicedeskplus.jp （获取请求列表示例为： https://servicedeskplus.jp/api/v3/requests)
加拿大 (CA)	https://servicedeskplus.ca （获取请求列表示例为： https://servicedeskplus.ca/api/v3/requests)
沙特阿拉伯 (SA)	https://servicedeskplus.sa/ （获取请求列表示例为： https://servicedeskplus.sa/api/v3/requests)
英国 (UK)	https://servicedeskplus.uk （获取请求列表示例为： https://servicedeskplus.uk/api/v3/requests)
中国 (CN)	https://servicedeskplus.cn （获取请求列表示例为： https://servicedeskplus.cn/api/v3/requests)
阿拉伯联合酋长国 (AE)	https://servicedeskplus.ae （获取请求列表示例为： https://servicedeskplus.ae/api/v3/requests)

重要

切勿硬编码单一区域的 URL。始终使用访问令牌响应中的 api_domain

有关数据中心的更多详情，请参见多数据中心支持.

API 示例

要访问 ManageEngine ServiceDesk Plus Cloud 的 API，您需要在请求中发送 ‘Authorization’ 和 ‘Accept’ 头。

获取列表请求

 https://sdpondemand.manageengine.com/api/v3/requests

重要

输入数据的 URI 组件需要在请求参数中进行编码。

Curl

$ curl -G <service domain|custom domain>/app/<portal>/api/v3/requests
      -X GET 
      -H "Accept: application/vnd.manageengine.sdp.v3+json" 
      -H "Authorization: Zoho-oauthtoken 1000.7xxx98976ab0xxxxxx19901e7551be57.bxxxx921ed64c04f79622bebcfxxxxxx" 
      -H "Content-Type: application/x-www-form-urlencoded"
      --data-urlencode input_data = 
 '{
  "list_info": {
    "search_criteria": {
      "field": "created_time.value",
      "condition": "greater than",
      "value": "1488451440000"
    }
  }
 }'

Deluge

// Deluge Sample script
url = "<service domain|custom domain>/app/<portal>/api/v3/requests";
headers = {"Accept":"application/vnd.manageengine.sdp.v3+json",
           "Content-Type": "application/x-www-form-urlencoded",
           "Authorization": "Zoho-oauthtoken 1000.7xxx98976ab0xxxxxx19901e7551be57.bxxxx921ed64c04f79622bebcfxxxxxx"};
input_data = {
  "list_info": {
    "search_criteria": {
      "field": "created_time.value",
      "condition": "greater than",
      "value": "1488451440000"
    }
  }
 };
params = {"input_data": input_data};
response = invokeurl
[
    url: url
    type: GET
    parameters: params
    headers: headers
];
info response;

Powershell

#Powershell version - 5.1
$url = "<service domain|custom domain>/app/<portal>/api/v3/requests"
$headers = @{"Accept"="application/vnd.manageengine.sdp.v3+json";
 "Authorization"="Zoho-oauthtoken 1000.7xxx98976ab0xxxxxx19901e7551be57.bxxxx921ed64c04f79622bebcfxxxxxx"}
$input_data = @'{
  "list_info": {
    "search_criteria": {
      "field": "created_time.value",
      "condition": "greater than",
      "value": "1488451440000"
    }
  }
 }'@
$data = @{ 'input_data' = $input_data}          
$response = Invoke-RestMethod -Uri $url -Method get -Body $data -Headers $headers -ContentType "application/x-www-form-urlencoded"
$response

Python

#Python version - 3.8
#This script requires requests module installed in python.
import requests
import json
url = "<service domain|custom domain>/app/<portal>/api/v3/requests"
headers ={"Content-Type": "application/x-www-form-urlencoded",
"Accept":"application/vnd.manageengine.v3+json",
"Authorization" : "Zoho-oauthtoken 1000.7xxx98976ab0xxxxxx19901e7551be57.bxxxx921ed64c04f79622bebcfxxxxxx"}
list_info ={"list_info": {"search_criteria": {"field": "created_time.value","condition": "greater than","value": "1488451440000"}}}
params = {"input_data" :json.dumps(list_info)}
response = requests.get(url,headers=headers,params=params,verify=False)
print(response.text)

    {
        "response_status": [{
            "status_code": 2000,
            "status": "success"
        }],
        "list_info": {
            "search_criteria": {
                "field": "created_time.value",
                "condition": "greater than",
                "value": "1488451440000"
            }
        },
        "requests": [{
            "subject": "Need an External Monitor",
            "id": "1928813039376938",
            "group": {
                "site": "Custom Site",
                "deleted": false,
                "name": "Hardware Problems",
                "id": "2173326968342823"
            },
            "requester": {
                "email_id": "lincoln@zmail.com",
                "is_technician": false,
                "sms_mail": "linc123@xys_sms.co",
                "phone": "test-phone",
                "name": "Lincoln",
                "mobile": "test-mobile",
                "id": "1650986973829395",
                "photo_url": "https://contacts.zoho.com/file?sample",
                "is_vip_user": false
            },
            "created_time": {
                "display_value": "Nov 10, 2016 11:44 AM",
                "value": "1478758440000"
            },
            "on_behalf_of": {
                "email_id": "lincoln@zmail.com",
                "is_technician": false,
                "sms_mail": "linc123@xys_sms.co",
                "phone": "test-phone",
                "name": "Lincoln",
                "mobile": "test-mobile",
                "id": "2437969736081554",
                "photo_url": "https://contacts.zoho.com/file?sample",
                "is_vip_user": false
            },
            "update_reason": "The request is updated for this reason",
            "has_notes": false,
            "status": {
                "in_progress": false,
                "internal_name": "test-internal_name",
                "stop_timer": false,
                "color": "#ffffff",
                "name": "Open",
                "id": "1846100140604337"
            },
            "template": {
                "is_service_template": false,
                "name": "Default Template",
                "id": "1908186594112074"
            },
            "display_id": "39",
            "is_service_request": false,
            "technician": {
                "email_id": "test@test.com",
                "cost_per_hour": 1343434.4333,
                "phone": "test-phone",
                "name": "Charles",
                "mobile": "test-mobile",
                "id": "1537931074919595",
                "photo_url": "https://contacts.zoho.com/file?sample",
                "sms_mail_id": "test-sms_mail_id"
            },
            "due_by_time": {
                "display_value": "Nov 10, 2016 11:44 AM",
                "value": "1478758440000"
            }
        }]
    }