DataCloud渠道用户注册和DataCloud动态token获取

v1.0.0

文档目的

本文档用于指导开发者对接数据云个人用户。

主要流程

1. 前往 https://datacloud.geovisearth.com 注册datacloud开发者账号。

2. 提供注册账号信息，联系管理员申请接入需要的 secretId,secretKey和对接的channelId信息。

3. 调用个人用户注册接口https://api.geovisearth.com/passport/datacloud/auth/phone （目前仅支持手机号）为个人用户申请应用,请存储返回的应用信息用于后续刷新token和获取用量时候用，在调用数据云服务的时候使用用户自己的token,这样消耗的是用户自己的配额。

4. 调用刷新token接口刷新个人应用token，由于个人应用的token信息有效期30分钟。所以在未过期之前，需要刷新token。

关于签名

为了防止token盗用，以下接口都需要进行签名校验,具体签名的步骤如下：
签名有效期5分钟，因此调用方需要小于5分钟的频率更新签名，私钥需要妥善保管，不应在网站页面中泄漏

签名说明

CloudApi使用文档

为什么要进行签名

签名通过以下方式帮助保护请求：

验证请求者的身份

保护传输中的数据

为了防止请求在传输过程中被篡改，需要在调用方使用请求参数来计算请求的哈希值，并将生成的哈希值加密后作为请求的一部分，发送到服务验证端。服务验证端使用收到的请求参数以同样的过程计算哈希值，并验证请求中的哈希值。如果请求被篡改，将导致哈希值不一致，服务验证端将拒绝本次请求。

签名有效期5分钟，因此调用方需要小于5分钟的频率更新签名，私钥需要妥善保管，不应在网站页面中泄漏。

签名过程

下面使用伪代码来详细解释签名计算过程。

1. 拼接规范请求串

按如下伪代码格式拼接规范请求串（CanonicalRequest）：

字段名称	解释
serviceName	访问的CloudApi的服务名称，此示例取值为 geovis-data-cloud
method	HTTP 请求方法（GET、POST ）。此示例取值为 POST
path	url的pathname部分，比如 https://datacloud.geovisearth.com/cloudapi/api1?query=123 中的 /cloudapi/api1
queryString	发起 HTTP 请求 URL 中的查询字符串，对于 POST 请求，固定为空字符串""，对于 GET 请求，则为 URL 中问号（?）后面的字符串内容，例如：Limit=10&Offset=0。注意：CanonicalQueryString 需要参考 RFC3986 进行 URLEncode，字符集 UTF8，推荐使用编程语言标准库，所有特殊字符均需编码。
body	发起 HTTP 请求 URL 中的body，对于不包含body的请求，固定为空字符串""，其他请求默认为body的json格式字符串
nonceStr	32位随机字符串，防重放攻击
timestamp	timestamp 必须是当前系统时间，且需确保系统时间和标准时间是同步的，如果落后标准时间超过五分钟，或者超过标准时间，会直接返回签名过期错误

2. 计算签名

计算派生签名密钥，伪代码如下：

请注意，不同的编程语言，HMAC 库函数中参数顺序可能不一样，请以实际情况为准。

字段名称	解释
SecretKey	原始的 SecretKey，即 aSLPPEDWNL77lBXmmE6B1Ii*******，需要将SecretKey按照base64格式还原为2进制密钥

signHex即签名后的得到的16进制字符串

3. 拼接 Authorization

按如下格式拼接 Authorization：

最终完整的调用信息如下：

将authorization添加到header中

随请求发送即可

GET 通过手机号授权并获取访问Token

GET /datacloud/auth/phone
Base URLs:

开发环境: https://api1.geovisearth.com/passport

线上环境: https://api.geovisearth.com/passport

通过手机号授权并获取访问Token

注意:
1.签名信息请携带到http header['auth']中，注意在签名时，path传递url的pathname部分，比如 https://api.geovisearth.com/passport/datacloud/auth/phone 中的path为: /datacloud/auth/phone
2.请在header中携带['referer'] referer 传固定值 https://datacloud.geovisearth.com

请求参数

名称	位置	类型	必选	说明
phone	query	string	是	手机号
channel	query	string	是	渠道ID

返回示例

200 Response

{
  "Success": true,
  "Code": 0,
  "Data":  {
      "createdTime": 1666923572257,
      "updatedTime": 1666972800107,
      "appName": "测试-默认应用",
      "developerId": "E7a1XNRKykaS0ubljtacr8HM4_cnanBd",
      "appId": "f-7pRrW6L2PuNaQi",
      "status": "normal",
      "secrecy": "public",
      "token": "428fbb28817602c49afeeec8615e82c3297b80878bd091e80daac7e4af7e908d",
      "referers": "",
      "emptyReferer": false
    },
  "Message": "string"
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	获取成功	ApiResult

GET public应用列表

GET /v1/cloudapi/application/myPublicAppList
注意:
1.请使用CloudApi签名方式进行签名
2.签名信息请携带到http header['authorization']中
base URL
开发环境 https://datacloud1.geovisearth.com
生产环境 https://datacloud.geovisearth.com

请求参数

名称	位置	类型	必选	说明
channel	query	string	是	ssoChannelId
mobile	query	string	是	手机号

返回示例

200 Response

{
  "statusCode": 0,
  "data": [
    {
      "createdTime": 1666923572257,
      "updatedTime": 1666972800107,
      "appName": "测试-默认应用",
      "developerId": "E7a1XNRKykaS0ubljtacr8HM4_cnanBd",
      "appId": "f-7pRrW6L2PuNaQi",
      "status": "normal",
      "secrecy": "public",
      "token": "428fbb28817602c49afeeec8615e82c3297b80878bd091e80daac7e4af7e908d",
      "referers": "",
      "emptyReferer": false
    }
  ]
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	success	string

POST 刷新应用的token

POST /v1/cloudapi/apps/public/{appId}/refresh
注意:
1.请使用CloudApi签名方式进行签名
2.签名信息请携带到http header['authorization']中
base URL
开发环境 https://datacloud1.geovisearth.com
生产环境 https://datacloud.geovisearth.com

请求参数

名称	位置	类型	必选	说明
appId	path	string	是	none
channel	body	string	是	ssoChannelId
mobile	body	string	是	用户的手机号

返回示例

201 Response

"string"

返回结果

状态码	状态码含义	说明	数据模型
201	Created	返回应用最近的两个token,按创建时间倒序	string

POST 签名验证

POST /v1/CloudApi/check

Body 请求参数

{
  "method": "string",
  "path": "string",
  "authorization": "string",
  "body": "string",
  "queryString": "string"
}

请求参数

名称	位置	类型	必选	说明
body	body	CloudApiCheckDto	否	none

返回示例

201 Response

{}

返回结果

状态码	状态码含义	说明	数据模型
201	Created	成功	Inline

返回数据结构

数据模型

CloudApiCheckDto

{
  "method": "string",
  "path": "string",
  "authorization": "string",
  "body": "string",
  "queryString": "string"
}

属性

名称	类型	必选	约束	说明
method	string	true	none	http method
path	string	true	none	url path
authorization	string	true	none	签名信息
body	string	true	none	http body,
queryString	string	true	none	http queryString,

GET 获取用量

GET /v1/cloudapi/developer/devDataPackUsage
注意:
1.请使用CloudApi签名方式进行签名
2.签名信息请携带到http header['authorization']中
base URL
开发环境 https://datacloud1.geovisearth.com
生产环境 https://datacloud.geovisearth.com

请求参数

名称	位置	类型	必选	说明
appId	query	string	是	应用id
channel	query	string	是	渠道id

返回示例

成功

{
  "statusCode": 0,
  "data": {
    "id": "EmCqIMyAU2objFjIa0hZdEeNFXkJ2vBG",
    "payload": null,
    "createTime": "2023-09-05T03:14:11.957Z",
    "updateTime": "2023-09-05T03:14:11.957Z",
    "deleteTime": null,
    "developerId": "iM6sa9ME-YIhwj1i01tZXpDakxdeNHiG",
    "type": 1,
    "trafficSpecify": "self",
    "status": "normal",
    "trafficLevel": "quota/su/su1",
    "trafficStartTime": 1693883651951,
    "trafficExpiretime": -1,
    "emptyReferer": false,
    "referers": null,
    "dataPack": {
      "key": "su1",
      "group": "su",
      "name": "个人免费版",
      "isFree": true,
      "isPublic": true,
      "traffic": {
        "interval": "day",
        "quota": 5000,
        "qps": 50
      },
      "currentUsage": 0
    }
  }
}

返回结果

状态码	状态码含义	说明	数据模型
200	OK	成功	Inline

DataCloud渠道用户注册和DataCloud动态token获取

DataCloud渠道用户注册和DataCloud动态token获取#

文档目的#

本文档用于指导开发者对接数据云个人用户。#

主要流程#

1. 前往 https://datacloud.geovisearth.com 注册datacloud开发者账号。#

2. 提供注册账号信息，联系管理员申请接入需要的 secretId,secretKey和对接的channelId信息。#

4. 调用刷新token接口刷新个人应用token，由于个人应用的token信息有效期30分钟。所以在未过期之前，需要刷新token。#

关于签名#

为什么要进行签名#

签名通过以下方式帮助保护请求：#

签名过程#

1. 拼接规范请求串#

2. 计算签名#

3. 拼接 Authorization#

GET 通过手机号授权并获取访问Token#

请求参数#

返回结果#

GET public应用列表#

请求参数#

返回结果#

POST 刷新应用的token#

请求参数#

返回结果#

POST 签名验证#

请求参数#

返回结果#

返回数据结构#

数据模型#

CloudApiCheckDto#

属性#

GET 获取用量#

请求参数#

返回结果#

DataCloud渠道用户注册和DataCloud动态token获取

文档目的

本文档用于指导开发者对接数据云个人用户。

主要流程

1. 前往 https://datacloud.geovisearth.com 注册datacloud开发者账号。

2. 提供注册账号信息，联系管理员申请接入需要的 secretId,secretKey和对接的channelId信息。

4. 调用刷新token接口刷新个人应用token，由于个人应用的token信息有效期30分钟。所以在未过期之前，需要刷新token。

关于签名

为什么要进行签名

签名通过以下方式帮助保护请求：

签名过程

1. 拼接规范请求串

2. 计算签名

3. 拼接 Authorization

GET 通过手机号授权并获取访问Token

请求参数

返回结果

GET public应用列表

请求参数

返回结果

POST 刷新应用的token

请求参数

返回结果

POST 签名验证

请求参数

返回结果

返回数据结构

数据模型

CloudApiCheckDto

属性

GET 获取用量

请求参数

返回结果