01 大纲
原文链接：
https://help.genesys.com/developer/cic/docs/icws/webhelp/ConceptualContent/GettingStarted_MakingRequests.htm#top
本主题包含以下部分：
- 一般要求
- 会话请求
- 启用响应压缩
- JavaScript示例
一、发出请求
由于 ICWS API 遵循Representational State Transfer（REST）设计模式，对API的请求是HTTP+JSON的请求格式。本节将描述如何格式化这些请求。
本主题包含以下部分：
1、一般请求
2、会话请求
3、启用响应压缩功能（Response Compression）
4、JavaScript示例
1、一般请求
ICWS 支持HTTP和HTTPS两种请求。出于安全原因，建议使用HTTPS（详细信息，请参阅HTTPS上的加密通信）
使用以下TCP端口：
· HTTP - 8018
· HTTPS - 8019
HTTP请求包含以下部分：
· HTTP方法
· URI
· 标头参数（请求头）
· 可选的邮件正文
（1）HTTP方法、标头参数、消息正文的JSON结构都在每个API的文档 中定义。
（2）URI由客户端应用程序使用文档中定义的资源路径和客户端应用程序发送的任何查询字符串参数构造。
（3）API中定义的大多数资源路径都包含替换点或模板替换。生成URI时，这些模板部分将替换为数据值。有关更多信息，请参阅资源URI。
以下是使用HTTPS从名为“icwsServer”的服务器获取版本信息的原始HTTP请求示例。
GET /icws/connection/features HTTP/1.1
Host: icwsServer:8019
2、会话请求
大多数 ICWS API 要求在向这些API发出请求之前建立会话。这些API需要3条重要信息才能成功：
- session ID，将用作URI中的模板参数。
- CSRF令牌 将在请求作为要发送
ININ-ICWS-CSRF-Token报头参数。 - HTTP Cookie值。
建立连接时，会在响应正文和响应头中提供会话ID和CSRF令牌。HTTP Cookie将根据RFC 6265发送。对于基于Web浏览器的应用程序，无法从JavaScript访问HTTP Cookie以防止会话劫持和Cookie被盗。
如果请求这些资源中的一个需要会话且会话无效或缺少其中一个数据，则该请求将被拒绝，并显示401 - 未经授权的响应。有关请求被拒绝的详细信息将包含在响应中。
以下示例显示使用PUT / icws / {sessionId} / status / user-statuses / {userId} API 设置用户状态。此示例假定以下内容：
- 与“icwsServer”的HTTPS连接。
- session ID为“1234”。
- CSRF token(令牌) 是“abcd”。
- 用户的ID是“user1”。
- 状态ID为“At Lunch”。
PUT /icws/1234/status/user-statuses/user1 HTTP/1.1
Host: icwsServer:8019
Content-Length: 23
ININ-ICWS-CSRF-Token: abcd
Cookie: icws_1234=dba2f460-58ce-47ba-85b3-1bcf4e1e526e
{"statusId":"At Lunch"}
3、启用响应压缩
ICWS API 可以利用HTTP压缩来完成响应。前提是：响应大小足够大以保证压缩，并且开启了客户端支持压缩的功能。
当客户端可以支持HTTP压缩时，客户端应该使用Accept-Encoding逗号分隔内容编码（根据HTTP 1.1规范）。对于基于Web浏览器的应用程序，在浏览器端设置此功能。
Accept-Encoding: gzip,deflate
API支持gzip并deflate在RFC 2616第3.5节中定义。
4、JavaScript示例
以下提供了从JavaScript发送请求的简单示例。该示例包括ICWS请求URI部分的常量，用于向需要会话的API发送请求。
var ICWS_URI_SCHEME = 'http://';
var ICWS_URI_PORT = '8018';
var ICWS_URI_PATH = '/icws';
var ICWS_REQUEST_TIMEOUT_MS = 60000;
/**
* Sends a request to an existing ICWS session.
* @param {String} server The server name where ICWS is
available.
* @param {String} sessionId The ICWS session ID.
* @param {String} icwsCsrfToken The ICWS CSRF token.
* @param {String} method The HTTP method of the request.
(ex: GET, POST, PUT, DELETE)
* @param {String} requestPath The uri fragment for the request.
The part after the sessionId template parameter.
(ex: /messaging/messages)
* @param {Object|String} payload The payload to send with the
request, as a string or JSON.
* @param {resultCallback} resultCallback The callback
to invoke with the response details.
If there is no existing session,
the callback will be invoked with a 0 status and empty object.
*/
function sendRequest(server, sessionId, icwsCsrfToken, method,
requestPath, payload, resultCallback) {
var xmlHttp, uri;
// Use an XHR to make the web service request.
xmlHttp = new XMLHttpRequest();
// Once it's available, process the request response.
xmlHttp.onreadystatechange = function() {
if (xmlHttp.readyState === 4) {
sendRequestCompleted(xmlHttp, sessionId, resultCallback);
}
};
// Create the base URI, using the ICWS port,
// with the specified server and session ID.
uri = ICWS_URI_SCHEME + server + ':' + ICWS_URI_PORT + ICWS_URI_PATH;
// Once a session has been established,
//subsequent requests for that session require its session ID.
// (This is not provided when establishing the initial connection.)
uri += '/' + sessionId;
// Add the specific ICWS request to the URI being built.
if (requestPath.substring(0, 1) !== '/') {
uri += '/';
}
uri += requestPath;
// Open the HTTP connection.
xmlHttp.open(method, uri, true);
// Specify that credentials should be used for the request,
// in order to work correctly with CORS.
xmlHttp.withCredentials = true;
xmlHttp.timeout = ICWS_REQUEST_TIMEOUT_MS;
// If the ICWS request is for an existing session,
// then the session's CSRF token must be set as
// a header parameter.
// (This is not provided when establishing the initial connection.)
xmlHttp.setRequestHeader('ININ-ICWS-CSRF-Token', icwsCsrfToken);
// The ICWS content-type must be specified.
xmlHttp.setRequestHeader('Content-type', ICWS_MEDIA_TYPE
+ ';' + ICWS_MEDIA_CHARSET);
// Allow JSON to be provided as an option, then convert it to a string.
if (typeof payload !== 'string' && !(payload instanceof String)) {
payload = JSON.stringify(payload);
}
// Send the request.
xmlHttp.send(payload);
}
/**
* The callback for receiving the result from {@link sendRequest}
or {@link sendSessionlessRequest}.
* @callback resultCallback
* @param {Number} status The HTTP status code of the response.
* @param {Object} jsonResponse The JSON response payload.
* @param {String} sessionId The ICWS session ID.
*/
/**
* Process the response to an ICWS request.
* @param {Object} xmlHttp The XMLHttpRequest instance for the request.
* @param {String} sessionId The session ID that was used, if any.
* @param {resultCallback} resultCallback The callback
to invoke with the result.
*/
function sendRequestCompleted(xmlHttp, sessionId, resultCallback) {
var status, responseText, response;
status = xmlHttp.status;
// Handle 401 failures as server disconnects.
if (status === 401) {
connectionStateChanged({
newConnectionState: 'down',
reason: 'No connection to server.'
});
}
// Process the response body.
responseText = xmlHttp.responseText;
if (responseText) {
try {
response = JSON.parse(responseText);
} catch(e) {
/* If the JSON cannot be parsed,
use an empty object for response. */
response = {};
}
} else {
response = {};
}
// Signal the request result to the caller's callback.
resultCallback(status, response, sessionId);
}