开发者中心

开发Services Java客户端

概述

本节介绍QuarkIoE 电子邮件和SMS短信 API,并显示如何使用QuarkIoE Java客户端访问它们。

使用Services平台

"services平台接口"负责从Java连接Services (电子邮件, SMS短信) API。


 ServicesPlatform platform = new ServicesPlatformImpl("<<URL>>", new QuarkioeCredentials("<<tenant>>", "<<user>>", "<<password>>", "<application key>"));
                      

例如, 指向平台的URL可以是https://demos.quarkioe.com,它将处理所有API请求。

访问Services API

通过Java客户端API发送电子邮件

电子邮件services的接口可以通过使用如下的方法从Java获得:


  EmailApi emailApi = platform.getEmailApi();
                       

如果您想从Java发送电子邮件,请构建电子邮件对象并调用电子邮件API的相应方法:


  Email email = EmailBuilder.aEmail().
  withTo("primarydestination@somemail.com").
  withCc("copydestination@somemail.com").
  withReplyTo("wheretoreply@somemail.com").
  withSubject("New incoming message").
  withText("Hello World!").
  build();
  HttpStatus httpStatus = emailApi.sendEmail(email);
                       

地址、抄送和密送字段可以包含多个值,如 withTo("to1@email.com", "to2@email.com")。 电子邮件还可以包含定义为com.quarkioe.model.email.Attachment类的对象的附件。

电子邮件API的调用返回请求的HTTP状态,如果电子邮件成功发送,则返回200 OK。

电子邮件管理端点

新端点POST到/email/emails,格式为json。 例如:


    POST /email/emails
    Host: ...
    Authorization: Basic ...
    Content-Type: application/json
    {
    "to": ["first@somemail.com", "second@somemail.com"],
    "cc": ["copydestination@somemail.com"],
    "replyTo": "wheretoreply@somemail.com",
    "subject": "New incoming message",
    "text": "Hello world!"
  }
                        
访问SMS短信API

以下代码段显示了如何从Java获取SMS短信API的句柄:


  SmsMessagingApi smsMessagingApi = platform.getSmsMessagingApi();
                        

使用此句柄,您可以通过调用其函数从Java发送和检索SMS短信。

前提条件

1.SMS网关微服务和租户选项设置

有关sms-gateway微服务的URL的信息应在租户选项中给出。 请使用我们的Rest API将此信息存储为以下内容:


    POST /tenant/options
    Host: ...
    Authorization: Basic ...

    {
    "category": "sms",
    "key": "microservice.url",
    "value": "<IP/Domain>:8688/sms-gateway"
  }
                        

2.分配所需角色

要使用用户的SMS短信API,用户群组应该具有必需的角色,例如用于发送的"SMS_ADMIN"和用于接收短信的"SMS_READ"。 请参考'分配帐户级权限'

3.选择SMS短信服务商

  • OpenIT

可以使用系统管理分配OpenIT凭证。 从菜单中单击OpenIT凭证并为您的租户保存这些凭据。

OpenIT凭证

请注意,此服务商不支持接收短信和接收特定短信。

  • Jasper控制中心

请参考Jasper控制中中心获取设置凭证信息。

  • Ericsson

对于此服务商,请使用我们的Rest API为每个键分别存储租户选项:


  POST /tenant/options
  Host: ...
  Authorization: Basic ...
                        

服务商:

 
 {
    "category": "messaging",
    "key": "provider",
    "value": "ericsson-dcp"
  }
                        

基本url:

 
 {
    "category": "messaging",
    "key": "ericsson-dcp.baseUrl",
    "value": "<url>"
  }
                        

用户名:

 
 {
    "category": "messaging",
    "key": "ericsson-dcp.username",
    "value": "<username>"
  }
                        

密码:

 
 {
    "category": "messaging",
    "key": "ericsson-dcp.password",
    "value": "<password>"
  }
                        

发送方地址:

 
 {
    "category": "messaging",
    "key": "sms.senderAddress",
    "value": "<发送所有SMS短信的电话号码(Ericsson DCP提供)>"
  }
                        

发送方名称:

 
 {
    "category": "messaging",
    "key": "sms.senderName",
    "value": "<关联到电话号码的名称>"
  }
                        

请注意,此服务商不支持接收特定短信。

  • Tropo

对于此服务商,请使用我们的Rest API为每个键分别存储租户选项:


  POST /tenant/options
  Host: ...
  Authorization: Basic ...
                        

服务商:

 
 {
    "category": "messaging",
    "key": "provider",
    "value": "tropo"
  }
                        

基本url:

  
  {
    "category": "messaging",
    "key": "tropo.baseUrl",
    "value": "<url>"
  }
                        

凭证:


 {
    "category": "messaging",
    "key": "tropo.credentials",
    "value": "<credentials>"
  }
                        

发送方地址:

 
 {
    "category": "messaging",
    "key": "sms.senderAddress",
    "value": "quarkioe"
  }
                        

发送方名称:

  
 {
    "category": "messaging",
    "key": "sms.senderName",
    "value": "quarkioe"
 }
                        

请注意,此运营商不支持接收短信和接收特定短信。

发送短信:

要使用API发送SMS短信,请使用"发送短信请求构建器"准备消息,并以此短信内容调用API的"发送短信"函数。


  SendMessageRequest smsMessage = SendMessageRequest.builder()
    .withSender(Address.phoneNumber("<电话号码>"))
    .withReceiver(Address.phoneNumber("<电话号码>"))
    .withMessage("<短信内容>")
    .build();

   smsMessagingApi.sendMessage(smsMessage);
                        
接收所有短信:

并不是所有的SMS服务商都支持接收短信。

要接收SMS短信可以使用以下API:


  smsMessagingApi.getAllMessages(Address.phoneNumber("<电话号码>"));
                        
接收特定短信:

并不是所有的SMS服务商都支持接收短信。

要接收特定SMS短信可以使用以下API:


  smsMessagingApi.getMessage(Address.phoneNumber("<电话号码>"), "<短信id>");
                        
SMS管理端点

要完成相同的行为,可以使用Rest API。

发送短信:


  POST /service/sms/smsmessaging/outbound/tel:<发送方电话号码>/requests
  Host: ...
  Authorization: Basic ...
  Content-Type: application/json
  {
  "outboundSMSMessageRequest": {
  "address": ["tel:<电话号码>"],
  "senderAddress": "tel:<电话号码>",
  "outboundSMSTextMessage": {
  "message": "<短信内容>"
 },
  "receiptRequest": {
  "notifyUrl": <通知url>,
  "callbackData": <回调数据>
},
  "senderName": <发送方名称>
  }
}
                          

接收所有短信:


  GET /service/sms/smsmessaging/inbound/registrations/tel:<接收方电话号码>/messages
  Host: ...
  Authorization: Basic ...

  HTTP/1.1 200 OK
  {
  "inboundSMSMessageList": [
  {
  "inboundSMSMessage": {
  "dateTime": "<日期>",
  "destinationAddress": "<目的地址>",
  "messageId": "<短信id>",
  "message": "<短信>",
  "resourceURL": "<资源url>",
  "senderAddress": "<发送方地址>"
  }
 ]
}
                          

接收特定短信:


  GET /service/sms/smsmessaging/inbound/registrations/tel:<接收方电话号码>/messages/<短信id>
  Host: ...
  Authorization: Basic ...

  HTTP/1.1 200 OK
  {
  "inboundSMSMessage": {
  "dateTime": "<日期>",
  "destinationAddress": "<目的地址>",
  "messageId": "<短信id>",
  "message": "<短信>",
  "resourceURL": "<资源url>",
  "senderAddress": "<发送方地址>"
  }
}