asapi(v2)でデータを要求する

更新しました

asapiは、 ricloud APIの非同期制御メカニズムです。これにより、ユーザーは次のことが可能になります。

  • 使用が許可されているサービスアクション 、およびエンドポイントを発見する
  • アカウントの登録、登録解除、および学習
  • 非同期タスクを送信する
  • タスクの状況を照会する

完了したら、 タスクからのデータは、クライアントのユースケースに応じて、aschannelまたはasstoreのいずれかから取得することができます。

一目でわかるメソッド

サービス、アクション、エンドポイントの発見

/account/

/account/エンドポイントを使用すると、クライアントは次の情報を入手できます。

  • 利用可能なサービス
  • 利用可能なアクションとそのパラメータおよび権限
  • タスクの送信と取得に利用可能なエンドポイント

そうするために、ディスカバリー要求が行われます。

$ 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アクションにアクセスできます。彼らはそれを使用するとき、そしてオプションでそれsincedevicedataパラメータを送信する必要があるでしょう。

この最後のdataパラメータはリスト形式でなければなりません。このパラメーターには、 fetch-dataセクションのpermissions > dataにリストされている任意の値を含めることができます。

task_submission_endpointはこの応答で定義され、アクションが実行のために送信される場所をクライアントに知らせます。

上記の例のstream_endpointaschannel.reincubate.comとして定義されています。つまり、 aschannelが結果エンドポイントとして構成されています。あるいは、トークンの設定によっては、これによりクライアントにストアを指示することもできます。

アカウント登録と登録解除

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>タスクの結果を取得するために使用する方法を示し、aschannelまたはasstoreの値を取ることができ<STREAM> * aschannelを使用している場合、タスクの結果を取得用のストリームIDであります

リクエストが不正な形式の場合、「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_idasapiエンドポイントに送信できます。そのステータスは/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/

少なくとも1つの正しい<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>パラメータは、ステータスチェック自体の成功を示します。これが "false"の場合、レスポンスには追加の "errors"エントリが含まれます。

考えられるエラーは次のとおりです。

  • 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時(GMT)です。 時間は現在 2:33 PM GMTです。

1営業日以内に、お返事を差し上げます。メールアドレスはこちら。

サポートセクションに移動 › エンタープライズチームに連絡する ›
私たちの素晴らしいサポートチーム

© 2008 - 2019 Reincubate Ltd. 無断複写・転載を禁じます。 イングランドとウェールズに登録 #5189175, VAT GB151788978. Reincubate®は登録商標です。 プライバシーと利用規約. マルチファクタ認証をお勧めします。 ロンドンで愛と建てられた。