はじめに
ricloud APIの使用を開始するには、最初に連絡して組織をセットアップする必要があります。これが完了すると、APIへのアクセスを許可する最初のkey_tokenが必要になります。
このセクションのAPI呼び出しはcURLを使用して実行されますが、これらはricloud-pyからの同等の呼び出しで簡単に置き換えることができます。
あなたの組織を見る
まず、あなたの組織について簡単に見ていきます。
curl 'https://ricloud-api.reincubate.com/organisation' \ -H 'Authorization: Token <your key_token>'
以下のような応答が表示されるはずです。 HTTP 401応答をkey_token場合は、 Authorizationヘッダーに指定したkey_token値を確認してください。
{ "id": 1, "resource": "organisation", "name": "Getting started", "slug": "getting-started", "permissions": { "id": 1, "resource": "organisation_permissions", "identifier": "default", "scopes": { "source_type:icloud.*": [], "task_type:*": [], "data_type:icloud.account.info": [], }, "date_created": "2018-11-22T12:59:57.168354Z" }, "storage_configs": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/storage" }, "storage_config_default": null, "webhook_configs": { "data": [], "has_more": false, "total_count": 0, "url": "/configs/webhook" }, "webhook_config_default": null, "state": "unconfigured", "date_created": "2018-11-22T12:59:57.016467Z" }
ここであなたはあなたの組織についてのいくつかの情報を見ることができます：
-
permissionsは、組織の基本permissions表示されます。 - まだ設定していないので、
storage_configsとstorage_config_defaultは空です。 -
webhook_configsとwebhook_config_defaultも同じ理由で空です。 -
stateはunconfiguredです。これは有効なストレージ構成がないことを反映しています。
これは後でAPIを介してサービスにアクセスすることを妨げるものではないため、設定手順に戻ります。
組織が稼働していることを確認したので、iCloudアカウントにアクセスしてみましょう。
セッションを設定する
セッションは、ソースへのアクセスを表します。この場合、ソースはiCloudアカウントであり、セッションを作成するとアカウントに事実上「ログイン」します。セッションは、APIとiCloudのシステム間の接続を追跡し、今後のリクエストに備えます。
ユーザーを作成する
セッションを設定する前に、どのエンドユーザーがソースにアクセスするかを定義するためのユーザーを作成する必要があります。これは、セッション管理とAPIのデータセキュリティに役立ちます。
curl 'https://ricloud-api.reincubate.com/users' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "identifier": "<some identifier for the user your system will recognise>" }'
応答には、次の呼び出しに必要なユーザーIDが含まれています。
{ "id": "1", "resource": "user", "organisation": "1", "key": "1", "identifier": "<your user identifier>", "state": "active", "date_created": "2018-11-22T13:49:37.215516Z" }
セッションを作成する
curl 'https://ricloud-api.reincubate.com/sessions' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "source": { "user": "<user ID from previous request>", "type": "icloud.account", "identifier": "<iCloud account username>" }, "payload": { "password": "<iCloud account password>" } }'
応答にはセッションリソースが含まれます。セッションリソースは、APIがサードパーティサービスとの通信をセットアップするプロセスを実行する間、最初はpending状態になります。
{ "id": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "resource": "session", "organisation": "1", "user": "1", "source": "1", "state": "pending", "error": null, "date_created": "2018-11-22T13:50:12.628776Z", "date_expired": null }
検索呼び出しを介してセッションの状態を確認できます。
curl 'https://ricloud-api.reincubate.com/sessions/ed855b07-f72b-4983-ac1d-980fafee8a0b' \ -H 'Authorization: Token <your key_token>'
状態がfailed場合、初期化プロセス中に問題が発生しました。詳細については、 error属性の値を確認してください。アカウントで2FAが有効になっていて、パスワードが正しい場合、発生したエラーはおそらくcode-required 。アカウントに接続されているiOSデバイスの1つに2FAコードの入力が求められます。手順（1）から再度呼び出すだけですが、今回はペイロードに2FAコードを含めます。
curl 'https://ricloud-api.reincubate.com/sessions' \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "source": { "user": "<user ID from previous request>", "type": "icloud.account", "identifier": "<iCloud account username>" }, "payload": { "password": "<iCloud account password>", "code": "<2FA code>" } }'
別のエラーが発生した場合は、 エラーのセクションで詳細を確認してください。
状態がactiveになると、セッションはソースからデータとファイルを取得するために使用できるようになります。
ただし、前述したように、組織はまだこのデータを受信するように構成されていません。
データとファイルの取得
APIがソースからデータの取得を開始する前に、データの公開先を知る必要があります。 APIは現在、 Google Cloud StorageおよびAmazon S3（AWS）ストレージバケットへの公開をサポートしています。これらは、組織に属するストレージ設定を介して設定する必要があります。 ストレージ構成設定のドキュメントに記載されている手順に従って、自分のバケットをAPIで使用できるようにします。
ストレージ構成を取得したら、組織の取得を再試行できます。これで、 stateはunconfiguredではなくactiveになります。
データの投票を作成する
投票を作成するために必要なのは、アクティブなセッションのIDと、取得するデータまたはファイルの詳細情報だけです。
curl https://ricloud-api.reincubate.com/polls \ -X POST \ -H 'Authorization: Token <your key_token>' \ -H 'Content-Type: application/json' \ -d '{ "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "payload": { "data_types": ["icpl.photos"], } }'
上記の呼び出しでは、 icpl.photosデータ型を要求していることに注意してください。別のタイプのデータを取得したい場合や、特にこのデータタイプに対する権限がない場合があります。必要に応じてこの値を代入してください。
これにより、 pendingまたはprocessing pending stateポーリングリソースが返されprocessing 。バックグラウンドで、APIはこの情報を取得するために必要な実際の作業を行うタスクも作成しました（タスクを以前に作成してセッションをセットアップするためにも作成しました）。
{ "id": "f1447e76-59f1-486b-942f-6b90e3570c63", "resource": "poll", "organisation": "1", "key": "1", "user": "1", "source": "1", "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "tasks_pending": [], "tasks_processing": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "tasks_completed": [], "results": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "processing", "date_created": "2018-11-22T14:20:52.211618Z", "date_started": "2018-11-22T14:20:52.731838Z", "date_completed": null }
この時点では空のresults属性に注意してください。これは、この投票から公開されたデータまたはファイルの参照が表示される場所です。結果は利用可能になったときに公開されるため、投票全体が完了する前に結果を取得できます。
リクエストされたすべてのデータとファイルがストレージに公開されると、投票の状態はcompleted変わります。
結果情報を取得する
これは、投票のresults属性を調べることによって行われます。
curl 'https://ricloud-api.reincubate.com/polls/f1447e76-59f1-486b-942f-6b90e3570c63' \ -H 'Authorization: Token <your key_token>'
応答には必要な情報が含まれています。
{ "id": "f1447e76-59f1-486b-942f-6b90e3570c63", "resource": "poll", "organisation": "1", "key": "1", "user": "1", "source": "1", "session": "ed855b07-f72b-4983-ac1d-980fafee8a0b", "tasks_pending": [], "tasks_processing": [], "tasks_completed": ["6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb"], "results": { "data": [ { "id": "754cfef0-7576-44c0-acfe-8b0d8d0dd32f", "resource": "result", "task": "6bdb82ad-28bf-4aad-ab2c-b4952a7aa3eb", "identifier": "data:info.account", "url": "<your storage config url>", "checksum": "2668324d21a20301ce71c28bc5e621d4", "size": 12345, "state": "available", "date_created": "2018-11-22T14:20:53.506542Z", "date_consumed": null, "date_deleted": null } ], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/results" }, "errors": { "data": [], "has_more": false, "total_count": 0, "url": "/polls/f1447e76-59f1-486b-942f-6b90e3570c63/errors" }, "state": "completed", "date_created": "2018-11-22T14:20:52.211618Z", "date_started": "2018-11-22T14:20:52.731838Z", "date_completed": "2018-11-22T14:20:53.548372Z" }
結果のurl属性はあなたのバケツに保存されているファイルを指します。
ウェブフックイベントを受信する
Reincubate Relayアプリが新しいデータを見つけるなどの外部トリガーの結果として、またはサブスクリプションが原因で、特定のAPI機能が自動的にトリガーされます。このような場合、APIには、変更が発生したこと、または注意が必要な新しいデータが公開されたことをシステムに通知する方法が必要です。
これを行うために、APIはWebhook通知を利用します。 APIがこれらの送信を開始する前、およびReincubate Relayサービスまたはサブスクリプションの使用を開始する前に、有効なWebhook構成で組織を構成する必要があります。詳細については、 Webhook構成のガイドに従ってください。
