Comm100 Email Marketing API学习小结

随着技术的更新，Comm100 Email Marketing API也进行了技术革新，

从使用 SOAP WebService过渡到了REST WebService。

SOAP 是用于访问网络服务的协议，最早是针对RPC的一种解决方案，

可使应用程序在 HTTP 之上进行信息交换。但随着SOAP的不断应用发

展，他也从一个轻量协议由于不断地附加内容而逐渐变成了一个重量协

议，使用越来越不便捷。

REST是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，

提高系统的可伸缩性。形式上应该表述为客户端通过申请资源来实现状态

的转换，在这个角度系统可以看成一台虚拟的状态机。

下面从几个方面比较这两种技术在我们Comm100中的区别（主要讲REST）：

1.支持的HTTP传输协议的方法

a.SOAP仅支持POST方法

b. REST支持GET，POST，PUT，DELETE方法（对应read, update,

create, delete这四种基本操作），后2种用得比较少，PUT方法用于添

加资源，DELETE方法用于删除资源，目前我们的API中只使用了前2种方

式。(Get方法URL中必须写出要求的全部参数,Post则不需要)

2.调用方法

a. SOAP Web Service的调用（对使用人员要求较高，需要有一定的开发基础）

i. 如果要对返回结果做后续处理，必须先添加Web Service的引用

ii. 如果Web Service中新增方法，所有调用该Web Service的用户必

须对引用的Web Service进行Update，否则访问不到新增的方法。

    iii. 在原有的方法增加参数也需要对引用进行Update，否则，调用的是

       老的方法而不会报错，导致信息的不对称，从而导致错误的结果。

b. REST的调用（利用URI定位到相应的资源）

    i. 提供URL即可进行访问，如目前我们中文版的新API，用户需要返回某个

       Contact的信息，最简单的方法（GET方法）是在浏览器中输入以下URL

       即可获得相应信息http://solution.comm100.cn/emailmarketingapi/contact/json/contact_get_by_id?apikey=***&contactid=***。

      使用起来简单方便，这不仅简化了调用复杂度，也降低了对使用人员的要求。

     注:①apikey明确地标识了Comm100用户的账户，通过它可以编辑对应用户账

          户中的联系人、发信等。

         ②contactid是用户账户中的某个存在的contact编号(没有账户的朋友,可以

            免费注册一个Email Marketing plan进行试用,来体验我们的API使用方法，注

            册地址：http://emailmarketing.comm100.com/)

      (具体调用方法文档可参见Comm100 API DOC:

       http://www.comm100.cn/emailmarketingnewsletter/newsletterApi.html

      )

    ii. 如果有新增方法，只需要开放新方法的调用URL及相应参数即可，不需要

      客户进行额外的一些操作。

    iii. 对已有方法增加参数，以GET方法为例，如果没有传递相应的参数，系统会

      返回错误信息。但对于Post方法其实与SOAP方式是一致的，需要手动判断用

      户是否传了相应的参数。

     iv. Post方式的提交，用户可以写一个纯HTML的表单，提交到API相应的链接，

      即可实现增删改等一系列的管理操作。

3.返回格式

a. SOAP比较单一，返回的是传统的XML格式

b. REST支持的返回格式比较多有XML，JSON, RSS,ATOM等形式（能很好的融

合目前web2.0需求）

4.安全性

a. SOAP在安全方面是通过使用XML-Security和XML-Signature两个规范组成了

WS-Security来实现安全控制

b. REST没有任何规范对于安全方面作说明，同时现在开放REST风格API的网站主

要分成两种，一种是自定义了安全信息封装在消息中（其实这和SOAP没有什么区别），

另外一种就是靠硬件SSL来保障，但是这只能够保证点到点的安全，如果是需要多点

传输的话SSL就无能为力了。像淘宝平台的API采用的添加签名参数这么一个机制，

签名密钥+再加上所有请求的参数。具体步骤是：

i. 第一步：把所有请求的参数名字母顺序排序

ii. 第二步：把所有参数名和参数值串在一起

iii. 第三步：使用MD5加密

iv. 第四步：把二进制转化为大写的十六进制

5.新API的代码实例

a. 用SDK调用新的API代码实例

C#（引用我们的Comm100Sdk.dll文件，可在http://www.comm100.cn/emailmarketingnewsletter/newsletterApi.html中下载）

private void ContactGetById ()

{

try

{

string url = "http://solution.comm100.cn/emailmarketingapi";

string appkey = "**";

string format = "xml"; // 数据返回格式，目前支持xml,json两种

ITopClient client = new DefaultTopClient(url, appkey, format);

ContactGetRequest req = new ContactGetRequest();

req.ContactId = 23;

ContactGetResponse response = client.Execute(req, sessionKey);

if (response.Error != null && response.Error.ErrorCode==0)

{

Response.Write("Email:" + response.Contact.Email);

}

catch (Exception exp)

{

}

JAVA

private static void ContactGetById() {

try {

String serverUrl = "http://solution.comm100.cn/emailmarketingapi";

String apikey = "**";

String Format = "json";

TopClient client = new DefaultTopClient(serverUrl, apikey, Format);

ContactGetRequest req = new ContactGetRequest();

req.setContactId(23L);

ContactGetResponse response = client.execute(req, "");

System.out.println(response.getContact().getEmail());

System.out.println(response.getBody());

} catch (ApiException e) {

e.printStackTrace();

}

b. 不使用SDK的后台调用API的方式（仅示例POST方式）

public string ContactGetById()

{

try

{

string apikey="**";

string contactid=23;

StringBuilder paras = new StringBuilder();

paras.Append("apikey=" + HttpUtility.UrlEncode(apikey));

paras.Append("contactid=" + HttpUtility.UrlEncode(contactid));

byte[] buffer = Encoding.UTF8.GetBytes(paras.ToString());

HttpWebRequest request = (HttpWebRequest)HttpWebRequest.Create("http://solution.comm100.cn/emailmarketingapi /contact/json/contact_get_by_id");

request.Method = "POST";

request.ContentType = "text/plain";

request.ContentLength = buffer.Length;

Stream requestStream = request.GetRequestStream();

requestStream.Write(buffer, 0, buffer.Length);

requestStream.Close();

Stream dataStream = request.GetResponse().GetResponseStream();

StreamReader r = new StreamReader(dataStream, Encoding.UTF8);

string strRetP = r.ReadToEnd();

return strRetP;

}

catch (Exception exp)

{

}

JAVA

/***

* 发起一个HTTP POST请求,并将返回的数据输出,这里使用的是apache httpclient

*

* @param url

* @param postData

* @return 返回结果

*/

private static String doClientPost(String url, NameValuePair[] postData) {

try {

HttpClient httpclient = new HttpClient();

PostMethod postMethod = new PostMethod(url);

postMethod.getParams().setParameter(

HttpMethodParams.HTTP_CONTENT_CHARSET, "utf-8");

if (postData != null) {

postMethod.addParameters(postData);

}

httpclient.executeMethod(postMethod);

String body = postMethod.getResponseBodyAsString();

postMethod.releaseConnection();

return body;

} catch (Exception e) {

e.printStackTrace();

}

return "";

}

c. HTML页面调用API方式

<body>
   <form action="http://solution.comm100.cn/emailmarketingapi/email/xml/email_get_all" method="post">
   apikey:<input type="text" name="apikey" value="**" />
   <br />
   ifreturnbody:<input type="text" name="ifreturnbody" value="true" />
   <br />
   start:<input type="text" name="start" value="1" />
   <br />
   limit:<input type="text" name="limit" value="2">
   <br />
   <input type="submit" value="submit" />
   </form>
</body>

如果将上面的method=”post”改成method=”get”将以get方式提交。SOAP方式

的Web Service就没办法采用这种简便的方式，需要构造一个SOAP消息来获取服

务，用得比较多的是用Ajax的HTTPRequest构建一个SOAP消息对webservice进

行调用，然后接受返回参数。

6.客户使用API的场景

a. SDK或后台进行调用的场景

i. 需要对返回结果做进一步处理。如把联系人的返回信息展示到自己的系统中。

ii. 客户有自己的系统，需要做数据同步，他需要把这个新增的联系人同时记录到

2个系统中。

譬如：有个北京客户，他有自己的系统，他的客户需要登陆到他的系统中进行操作，

他希望他的客户可以直接在他们的系统中对Email或是Contact等功能进行操作。

那么在他的系统需要我们Email Marketing后台的绝大部分功能。这样的客户，他

们就需要使用我们提供的SDK和后台调用或是用户自己写客服端调用我们的API。

b. HTML，JS等前台直接调用的场景

i. 譬如订阅，反订阅这种功能，

ii. 有些客户可能需要经常添加1，2个联系人，但他又不想登陆到我们系统。于是

他只要写一个备用的HTML页面，填写相应的信息提交即可。

iii. 适用于知道一些基本HTML知识，太复杂的东西不会弄的客户。

c. 直接在浏览器输入URL请求（GET方法）返回结果的，适合查看单条信息。譬如

我想看一下刚才添加的那条联系人信息是否正确。

posted @ 2013-04-15 17:14 Comm100 Testers 阅读(426) 评论(0) 编辑收藏举报

刷新页面返回顶部