增加 tag, alias 相关接口

Author: liyangliang

Diff for: README.md

@@ -185,6 +185,6 @@ if err != nil {
 }
 ```
 
-## 4. 完整示例
+## 4. 更多示例
 
-完整的示例可以直接运行，代码在这里：[examples/push.go](examples/push.go)
+更多例子可以看这里：[jpush_test.go](jpush_test.go)

Diff for: common/consts.go

@@ -7,10 +7,27 @@ const (
 	rateLimitRemainingHeader = "X-Rate-Limit-Remaining"
 	rateLimitResetHeader     = "X-Rate-Limit-Reset"
 
-	PUSH_URL          = "https://api.jpush.cn/v3/push"
-	PUSH_VALIDATE_URL = "https://api.jpush.cn/v3/push/validate"
+	push_host   = "https://api.jpush.cn"
+	device_host = "https://device.jpush.cn"
 
-	DEVICE_URL = "https://device.jpush.cn/v3/devices/%s"
+	PUSH_URL          = push_host + "/v3/push"
+	PUSH_VALIDATE_URL = push_host + "/v3/push/validate"
+
+	// GET /v3/devices/{registration_id}
+	DEVICE_URL = device_host + "/v3/devices/%s"
+
+	QUERY_TAGS_URL = device_host + "/v3/tags/"
+	// GET /v3/tags/{tag_value}/registration_ids/{registration_id}
+	CHECK_TAG_USER_EXISTS_URL = device_host + "/v3/tags/%s/registration_ids/%s"
+	// POST /v3/tags/{tag_value}
+	UPDATE_TAG_USERS_URL = device_host + "/v3/tags/%s"
+	// DELETE /v3/tags/{tag_value}
+	DELETE_TAG_URL = device_host + "/v3/tags/%s"
+
+	// GET /v3/aliases/{alias_value}
+	QUERY_ALIAS_URL = device_host + "/v3/aliases/%s"
+	// DELETE /v3/aliases/{alias_value}
+	DELETE_ALIAS_URL = device_host + "/v3/aliases/%s"
 )
 
 var (

Diff for: common/structures.go

@@ -11,7 +11,7 @@ type ErrorResult struct {
 }
 
 func (pe *ErrorResult) String() string {
-	return fmt.Sprintf("{code: %d, message: %s}", pe.Code, pe.Message)
+	return fmt.Sprintf("{code: %d, message: \"%s\"}", pe.Code, pe.Message)
 }
 
 type RateLimitInfo struct {
@@ -50,10 +50,26 @@ type ResponseBase struct {
 }
 
 func NewResponseBase(resp *http.Response) ResponseBase {
-	return ResponseBase{
+	rb := ResponseBase{
 		StatusCode:    resp.StatusCode,
 		RateLimitInfo: NewRateLimitInfo(resp),
 	}
+	if !rb.Ok() {
+		RespToJson(resp, &rb)
+	}
+	return rb
+}
+
+// 根据请求返回的 HTTP 状态码判断推送是否成功
+// 规范：
+// - 200 一定是正确。所有异常都不使用 200 返回码
+// - 业务逻辑上的错误，有特别的错误码尽量使用 4xx，否则使用 400。
+// - 服务器端内部错误，无特别错误码使用 500。
+// - 业务异常时，返回内容使用 JSON 格式定义 error 信息。
+//
+// 更多细节： http://docs.jpush.io/server/http_status_code/
+func (rb *ResponseBase) Ok() bool {
+	return rb.StatusCode == http.StatusOK
 }
 
 func (rb *ResponseBase) String() string {

Diff for: common/util.go

@@ -11,7 +11,7 @@ import (
 
 func BasicAuth(username, password string) string {
 	auth := username + ":" + password
-	return base64.StdEncoding.EncodeToString([]byte(auth))
+	return "Basic " + base64.StdEncoding.EncodeToString([]byte(auth))
 }
 
 func RespToJson(resp *http.Response, dest interface{}) error {
@@ -20,10 +20,18 @@ func RespToJson(resp *http.Response, dest interface{}) error {
 	if err != nil {
 		return err
 	}
-
+	println(string(body))
 	return json.Unmarshal(body, &dest)
 }
 
+func ResponseOrError(resp *http.Response, err error) (*ResponseBase, error) {
+	if err != nil {
+		return nil, err
+	}
+	ret := NewResponseBase(resp)
+	return &ret, nil
+}
+
 func GetIntHeader(resp *http.Response, key string) (int, error) {
 	v := resp.Header.Get(key)
 	return strconv.Atoi(v)

Diff for: device/alias.go

@@ -1 +1,27 @@
 package device
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/DeanThompson/jpush-api-go-client/common"
+)
+
+type GetAliasUsersResult struct {
+	common.ResponseBase
+
+	RegistrationIds []string `json:"registration_ids"`
+}
+
+func (result *GetAliasUsersResult) FromResponse(resp *http.Response) error {
+	result.ResponseBase = common.NewResponseBase(resp)
+	if !result.Ok() {
+		return nil
+	}
+	return common.RespToJson(resp, &result)
+}
+
+func (result *GetAliasUsersResult) String() string {
+	return fmt.Sprintf("<GetAliasUsersResult> RegistrationIds: %v, %v",
+		result.RegistrationIds, result.ResponseBase)
+}

Diff for: device/device.go

@@ -8,28 +8,24 @@ import (
 	"github.com/DeanThompson/jpush-api-go-client/common"
 )
 
-// 设备的所有属性，包含tags, alias
-type DeviceInfo struct {
+type QueryDeviceResult struct {
+	common.ResponseBase
+
+	// 设备的所有属性，包含tags, alias
 	Tags  []string `json:"tags"`
 	Alias string   `json:"alias"`
 }
 
-type DeviceInfoResult struct {
-	common.ResponseBase
-	DeviceInfo
-}
-
-func (dir *DeviceInfoResult) FromResponse(resp *http.Response) error {
-	err := common.RespToJson(resp, &dir)
-	if err != nil {
-		return err
-	}
+func (dir *QueryDeviceResult) FromResponse(resp *http.Response) error {
 	dir.ResponseBase = common.NewResponseBase(resp)
-	return nil
+	if !dir.Ok() {
+		return nil
+	}
+	return common.RespToJson(resp, &dir)
 }
 
-func (dir *DeviceInfoResult) String() string {
-	return fmt.Sprintf("<DeviceInfoResult> tags: %v, alias: %s, %v",
+func (dir *QueryDeviceResult) String() string {
+	return fmt.Sprintf("<QueryDeviceResult> tags: %v, alias: \"%s\", %v",
 		dir.Tags, dir.Alias, dir.ResponseBase.String())
 }
 
@@ -49,11 +45,15 @@ type DeviceUpdate struct {
 
 	// 更新设备的别名属性；当别名为空串时，删除指定设备的别名；
 	Alias string
+
+	// 手机号码
+	Mobile string
 }
 
 type deviceUpdateWrapper struct {
-	Tags  interface{} `json:"tags"`
-	Alias string      `json:"alias"`
+	Tags   interface{} `json:"tags"`
+	Alias  string      `json:"alias"`
+	Mobile string      `json:"mobile"`
 }
 
 func NewDeviceUpdate() *DeviceUpdate {
@@ -70,6 +70,7 @@ func (du *DeviceUpdate) MarshalJSON() ([]byte, error) {
 		wrapper.Tags = du.Tags
 	}
 	wrapper.Alias = du.Alias
+	wrapper.Mobile = du.Mobile
 	return json.Marshal(wrapper)
 }
 
@@ -92,3 +93,7 @@ func (du *DeviceUpdate) ClearAllTags() {
 func (du *DeviceUpdate) SetAlias(alias string) {
 	du.Alias = alias
 }
+
+func (du *DeviceUpdate) SetMobile(mobile string) {
+	du.Mobile = mobile
+}

Diff for: device/tag.go

@@ -1 +1,87 @@
 package device
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/DeanThompson/jpush-api-go-client/common"
+)
+
+// 查询标签列表请求结果
+type GetTagsResult struct {
+	common.ResponseBase
+
+	Tags []string `json:"tags"`
+}
+
+func (tir *GetTagsResult) FromResponse(resp *http.Response) error {
+	tir.ResponseBase = common.NewResponseBase(resp)
+	if !tir.Ok() {
+		return nil
+	}
+	return common.RespToJson(resp, &tir)
+}
+
+func (tir *GetTagsResult) String() string {
+	return fmt.Sprintf("<GetTagsResult> tags: %v, %v", tir.Tags, tir.ResponseBase.String())
+}
+
+// 判断设备与标签的绑定请求结果
+type CheckTagUserExistsResult struct {
+	common.ResponseBase
+
+	Result bool `json:"result"`
+}
+
+func (result *CheckTagUserExistsResult) FromResponse(resp *http.Response) error {
+	result.ResponseBase = common.NewResponseBase(resp)
+	if !result.Ok() {
+		return nil
+	}
+	return common.RespToJson(resp, &result)
+}
+
+func (result *CheckTagUserExistsResult) String() string {
+	return fmt.Sprintf("<CheckTagUserExistsResult> result: %v, %v", result.Result, result.ResponseBase)
+}
+
+// 更新标签（与设备的绑定的关系）请求参数
+const (
+	actionAdd                     = "add"
+	actionRemove                  = "remove"
+	maxAddOrRemoveRegistrationIds = 1000
+)
+
+type UpdateTagUsersArgs struct {
+	RegistrationIds map[string][]string `json:"registration_ids"`
+}
+
+func NewUpdateTagUsersArgs() *UpdateTagUsersArgs {
+	return &UpdateTagUsersArgs{
+		RegistrationIds: make(map[string][]string),
+	}
+}
+
+func (args *UpdateTagUsersArgs) AddRegistrationIds(ids ...string) {
+	args.updateRegistrationIds(actionAdd, ids...)
+}
+
+func (args *UpdateTagUsersArgs) RemoveRegistrationIds(ids ...string) {
+	args.updateRegistrationIds(actionRemove, ids...)
+}
+
+func (args *UpdateTagUsersArgs) updateRegistrationIds(action string, ids ...string) {
+	if action != actionAdd && action != actionRemove {
+		return
+	}
+	ids = common.UniqString(ids)
+	current := args.RegistrationIds[action]
+	if current == nil {
+		current = make([]string, 0, len(ids))
+	}
+	merged := common.UniqString(append(current, ids...))
+	if len(merged) > maxAddOrRemoveRegistrationIds {
+		merged = merged[:maxAddOrRemoveRegistrationIds]
+	}
+	args.RegistrationIds[action] = merged
+}