使用asapi请求数据(v2)

更新

asapiricloud API的异步控制机制。它使用户能够:

  • 发现他们有权使用的服务操作和终端
  • 注册,注销并了解帐户
  • 提交异步任务
  • 查询任务状态

完成后,可以从aschannelasstore获取任务中的数据,具体取决于客户端的用例。

方法一目了然

服务,操作和端点发现

/account/

使用/account/ endpoint,客户端可以获取以下信息:

  • 可用服务
  • 可用操作及其参数和权限
  • 可用于任务提交和检索的端点

为此,发出了一个发现请求:

$ curl \
    -X GET \
    -H 'Authorization: Token <TOKEN>' \
    https://asapi.reincubate.com/account/ -D -

这将返回一组描述可用服务,操作和端点的JSON。以下示例缩写为:

{ "services": [{
    "name": "iCloud",
    "actions": [{
      "description": "",
      "parameters": [{
        "type": "string",
        "description": "",
        "optional": false,
        "name": "Device",
        "slug": "device"
      }, {
        "type": "date",
        "description": "",
        "optional": true,
        "name": "Since",
        "slug": "since"
      }],
      "name": "Fetch Data",
      "execution": "Asynchronous",
      "slug": "fetch-data",
      "permissions": {
        "data": ["sms"]
      }
    }],
    "slug": "icloud"
  }],
  "task_submission_endpoint": {
    "host": "asapi.reincubate.com",
    "protocol": "https",
    "uri": "/submit-task/"
  },
  "stream_endpoints": [{
    "host": "aschannel.reincubate.com",
    "protocol": "https",
    "uri": "/stream/"
  }]
}

在这种情况下,客户端可以访问icloud服务和fetch-data操作。他们需要在使用时提交devicedata参数,也可以since提交。

最后一个data参数必须是列表格式;此参数可以包含fetch-data部分的permissions > data中列出的任何值。

task_submission_endpoint在此响应中定义,它通知客户端可以提交执行的操作。

上例中的stream_endpoint定义为aschannel.reincubate.com ,这意味着aschannel被配置为结果端点。或者,这可以将客户端定向asstore ,具体取决于其令牌的配置。

帐户注册和注销

register-account

为了提交行动,我们需要告知asapi可能对其执行操作的帐户。为此,我们将使用/register-account/ endpoint:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/register-account/ -D -

在此请求中, <SERVICE>是拥有特定操作的服务,而<USERNAME>表示将在操作中使用的帐户。

deregister-account

如果不再使用帐户,可以取消注册。要取消注册帐户,可以向/deregister-account/ endpoint发送类似的请求:

$ curl \
    -X POST \
    -H 'Authorization: Token <TOKEN>' \
    -d "service=<SERVICE>" \
    -d "username=<USERNAME>" \
    https://asapi.reincubate.com/deregister-account/ -D -

成功时,这两种方法都会返回200响应

{ "success": true
}

可能的错误包括:

  • unique_together :“此服务的帐户,客户端和用户名已存在”

任务提交

[TASK-SUBMISSION]

可以使用task_submission_endpoint指定的端点提交异步任务。

要提交任务,请使用以下命令:

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "service=<SERVICE>" \
    -d "action=<ACTION>" \
    -d "account=<ACCOUNT>" \
    -d "param1=<VALUE1>" \
    -d "param2=<VALUE2>" \
    <TASK_SUBMISSION_ENDPOINT> -D -

根据该要求:

成功后,请求将返回200

{ "task_id": "<TASK_ID>",
  "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
  "stream": "<STREAM>",
  "success": true
}

在这些响应中: <TASK_ID>提供任务的ID,可用于查询其状态并检索任务的结果(如果使用 asstore) <RETRIEVAL_PROTOCOL>指示用于检索任务结果的方法,并且可以获取aschannelasstore的值<STREAM>是流ID,用于检索任务的结果(如果使用 aschannel *)

如果请求格式错误,则“success”属性将为false,并且响应将包含带有反馈的“errors”部分。例如:

{ "errors": {
    "service": [
      ["[u'Invalid service name']", "invalid_service"]
    ]
  },
  "success": false
}

可能的错误包括:* invalid_service :'无效的服务名'* invalid_parameter_value :'参数不允许的值'* no_such_account :'没有这样的帐号'* invalid :'无效值'* limit_exceeded :'提交的任务ID太多'* invalid_action : '无效动作'* missing-param :'参数不见了'

查询任务状态

/task-status/

对于提交给asapi端点的每个任务,都提供了task_id 。客户端可以定期将此task_id提交到asapi端点,以便发现任务的状态。可以使用/task-status/ endpoint上的POST请求查询其状态。客户端可以同时请求最多10,000个任务的状态。

$ curl \
    -X POST \
    -H "Authorization: Token <TOKEN>" \
    -d "task_ids=<TASK_ID_1>,<TASK_ID_2>,<TASK_ID_3>,<TASK_ID_4>,<TASK_ID_5>,<TASK_ID_6>,<TASK_ID_7>" \
    https://asapi.reincubate.com/task-status/

给定至少一个正确的<TASK_ID> ,响应将是这种格式的200:

{ "<TASK_ID_1>": {
    "status": "<TASK_STATUS>",
    "retrieval_protocol": "<RETRIEVAL_PROTOCOL>",
    "result_retrieved": "<RETRIEVAL_STATUS>",
    "success": "<TASK_SUCCESS>"
  },
  "success": "<CHECK_SUCCESS>"
}

如果<TASK_SUCCESS>为“True”,则结果立即在适当的端点处可用。

status属性可以采用以下值:

  • Pending
  • In progress
  • Work complete
  • Publish ongoing, with result available
  • Publish complete (在这种情况下, success值为“true”)
  • Publish failed (在这种情况下, success值为“false”)
  • Task did not complete successfully. (在这种情况下, success值为“false”)

<RETRIEVAL_PROTOCOL> indicates the method used to retrieve the task results and can take the value of aschannel or asstore depending on the token.

<RETRIEVAL_STATUS> is a boolean, indicating whether the task's results have already been consumed by a client. If <RETRIEVAL_STATUS> is "True", then the results have already been consumed and are no longer available.

位于JSON树根目录的<CHECK_SUCCESS>参数指的是状态检查本身的成功。如果这是“假”,则响应将包含其他“错误”条目。

可能的错误包括:

  • invalid :“无效的task_id值:
  • limit_exceeded :“提交的任务ID太多,限制为

输出示例如下所示:

{
  "<TASK_ID_1>": {
    "success": false,
    "error": "No task with this ID was found."
  },
  "<TASK_ID_2>": {
    "status": "Publish complete",
    "retrieval_protocol": "aschannel",
    "result_retrieved": false,
    "success": true
  },
  "<TASK_ID_3>": {
    "status": "Publish complete",
    "retrieval_protocol": "asstore",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/",
    "result_retrieved": true,
    "success": true
  },
  "<TASK_ID_4>": {
    "status": "Publish failed",
    "retrieval_endpoint": "https://asstore.reincubate.com/fetch/1111111-2222-3333-4444-555555555555/",
    "success": false,
    "error": "Task did not complete successfully.",
    "retrieval_protocol": "asstore",
    "result_retrieved": false
  },
  "<TASK_ID_5>": {
    "status": "Pending",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_6>": {
    "status": "In progress",
    "result_retrieved": false,
    "success": false
  },
  "<TASK_ID_7>": {
    "status": "Work complete",
    "result_retrieved": false,
    "success": false
  },
  "success": true,
}

我们能帮你什么吗?

我们的支持团队在这里提供帮助!

我们的办公时间是格林威治标准时间周一至周五上午9点至下午5点。 时间目前是 5:36 PM的 GMT。

我们力争在一个工作日内答复所有垂询。

转到支持部分 › 联系企业团队 ›
我们的支持团队非常棒

© 2008 - 2019 Reincubate Ltd. 保留所有权利。 在英格兰和威尔士注册 #5189175, VAT GB151788978. Reincubate®是注册商标。 隐私权和条款. 我们推荐多因素认证。 在伦敦建立了爱情。