Platio APIは、Platio Studioで作成したミニアプリのレコードや添付ファイルを操作するためのWeb APIです。通常、ミニアプリを作成して配布すると、Platioアプリを使ってレコードを閲覧・作成・更新したり、データビューアーを使用して、レコードをインポート・エクスポートします。Platio APIは、プログラミングを通してレコードを操作するもう一つの方法です。
このドキュメントでは、Platio APIを使ってどのようにレコードを操作するかを説明します。このドキュメントは、Platio StudioやPlatioアプリ、データビューアーに慣れ親しんでいることを前提としています。もし、これらに慣れていない場合、まず、Platio Studioでミニアプリを作成して使ってみてください。
Platio APIを使うとミニアプリのレコードや添付ファイルを操作することができますが、ミニアプリ自体を作成・更新・削除することはできません。ミニアプリはPlatio Studioで作成し、配布する必要があります。ミニアプリを配布すると、Platio APIで、そのミニアプリのレコードにアクセスすることができます。
Platio APIを使う前に、いくつか知っておく必要のある用語があります。Platio APIでは、いくつかの内部的な名前を使用します。このため、いくつかの名前はPlatio Studioで使われている名前と異なります。
まず、ミニアプリは、Platio
APIではアプリケーションと呼ばれます。アプリケーションは、pから始まる27桁の文字列のIDで識別されます。pkyfjjjmlyffnlgeb5oh2eqs2aaはアプリケーションIDの例です。データビューアーの開発者ページで、アプリケーションのIDを確認することができます。
アプリケーションは、一つ以上のコレクションを持ちます。各データポケットはコレクションと関連付けられています。データポケットでレコードを作成すると、そのデータポケットに関連付けられたコレクションにレコードが保存されます。コレクションは、RDBにおけるテーブルのようなものです。コレクションは、tf71dbb9のような、tから始まる8桁の文字列のIDで識別されます。
コレクションは、カラムのリストを持ちます。カラムは、コレクションに保存されるレコードに、どのような型の値が保存されるかを定義します。Platio
Studioでフィールドを作成すると、カラムが作成されて関連付けられます。カラムはIDと、いくつかのプロパティを持ちます。カラムIDは、c002c2c0のような、cから始まる8桁の文字列です。カラムの型には、String、Number、Attachmentといったものがあります。カラムは、RDBにおけるカラムのようなものです。
コレクションやカラムのリストは、データビューアーの開発者ページで確認することができます。
Platioアプリでレコードを作成したり、データビューアーでレコードをインポートすると、コレクションにレコードとして保存されます。レコードは、rから始まる27桁の文字列のIDで識別されます。例えば、ri5f3cykexfbkzk7ohzqm2oocniはレコードIDです。レコードを取得・更新・削除するときには、このレコードIDを使用します。
レコードは、値の集合とメタデータから成ります。値の集合は、カラムIDから値へのマッピングです。Platio APIを使ってレコードを取得すると、以下のようなデータが返されます。
{
"id": "ri5f3cykexfbkzk7ohzqm2oocni",
"createdAt": "2016-07-20T11:39:50.007Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-20T11:39:50.007Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "3a73153a4a7abc176a3fa5dd538b8bda41e9d68d",
"timestamp": "2016-07-20T11:39:50.050Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "My Name"
},
"cfe0266a": {
"type": "Attachment",
"id": "ac2lzz2afdvguze5znhselxd4oe",
"contentType": "image/jpeg",
"name": "image.jpeg",
"size": 254179
},
"c915a0bc": {
"type": "Number",
"value": 28
}
}
}上の例でわかるように、それぞれの値は、typeプロパティと他のいくつかのプロパティを持ちます。どのようなプロパティを持つかは、型によって異なります。値に含まれる型は、カラムで指定した型と同じである必要があります。例えば、カラムで指定した型がStringならば、そのカラムの値はString型でなければなりません。型と値については、型と値を参照してください。
画像やビデオ、音声は、添付ファイルとして扱われます。例えば、画像を含むレコードを作成すると、画像自体はレコードには保存されず、添付ファイルとして別途保存されます。レコードは、その添付ファイルを参照する値を保持します。添付ファイルは、ac2lzz2afdvguze5znhselxd4oeのような、aから始まる27桁の文字列のIDで識別されます。
各アプリケーションは、ユーザーのリストを持っています。各ユーザーは、IDと名前の組み合わせです。ユーザーIDは、uf598c3fのようなuから始まる8桁の文字列です。Platioアプリやデータビューアーにログインするときには、ユーザーの名前を使用しますが、Platio
APIの認証では、ユーザーIDを使用します。
上で述べたように、Platio APIを使うためには、まずミニアプリを作成し、配布する必要があります。ミニアプリを配布したら、ユーザーを作成し、Platio APIを使用できるようにします。ユーザーがPlatio APIを使用できるようにするには、ユーザーを作成・編集するときに、「APIでのレコードや添付ファイルへのアクセスを許可」をチェックします。
なお、/v1/management/以下のエンドポイントを使用するAPIは管理APIです。管理APIを使用するには、ユーザーの作成・編集ページで、「APIでのレコードや添付ファイルへのアクセスを許可」に加えて「APIでのユーザーの管理を許可」をチェックします。詳細はPlatio 管理 API
プログラミングガイドをご覧ください。
ここで、データビューアーでそのミニアプリにログインし、開発者ページを開いてください。このページで、Platio APIを使うための情報を確認することができます。
このドキュメントでは、「名前」テキストフィールド、「写真」画像フィールド、「年齢」数値フィールドを持つヒッツのデータポケットを含んだミニアプリを作成したと仮定します。以下が必要な情報になります。実際にPlatio APIを使うときには、自身のミニアプリの開発者ページの情報で置き換えてください。
pkyfjjjmlyffnlgeb5oh2eqs2aatf71dbb9c002c2c0Stringcfe0266aAttachmentc915a0bcNumberuf598c3fuser1mypasswordt2fde9481edc1a2be612c563d52619b3825f77ff757f16dfcff1d414874731594S7HAvwFqCUexNe7~PVVEiz-MZkwI2icqLn1RJaS84MANVmiCYq8geIlKsq-K/yrtHTxyXTnF-WXmkZmwWeVt8AK7pyU7E06uv+cSWInqBh7q/yGrtNllwQqss33F5gXLpsyEm4KLcBZ8D2O4-7qXPfAM3YRgBey3ivD5tZTq1-lY8ENIRki~4v6q3bLKHar/aR+0wL8QX+UlFqdOyzNIJ0nhyO5w_7_5Fb_xb4h9VeLc479EPO3X9B_JX09LNcTRPlatio
APIのエンドポイントは、https://api.plat.io/v1/に、アプリケーションIDを繋げたものです。例えば、コレクション内のレコードを取得するためのURLは、https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/recordsになります。
Platio APIでは、添付ファイル関係での一部の例外を除いて、リクエストやレスポンスの形式としてJSONを使用します。例えば、レコードを取得すると、JSON形式でレコードが返されます。レコードを作成・更新するには、JSON形式でデータを送信します。
このため、レスポンスのContent-Typeは、application/jsonになります。また、POSTやPUTリクエストを送る際には、Content-Typeとしてapplication/jsonを指定する必要があります。
Platio APIを使用するときには、自身を認証する必要があります。現在、Platio APIは、Bearer認証とBasic認証をサポートしていますが、Bearer認証を使用することを推奨します。
Bearer認証を使用して認証を行なうには、APIトークンを使用します。
APIトークンは、データビューアーの開発者ページで生成することができます。このトークンは、トークンIDと秘密トークンを.で繋げたものです。秘密トークンは、セキュリティ上の理由により、生成時にしか表示されず、生成後は開発者ページにはトークンIDしか表示されません。秘密トークンを忘れた場合には、現在のAPIトークンを無効にして、新しいAPIトークンを生成する必要があります。
APIトークンは、AuthorizationヘッダーにBearer認証の指定とともに指定します。
Authorization: Bearer t2fde9481edc1a2be612c563d52619b3825f77ff757f16dfcff1d414874731594.S7HAvwFqCUexNe7~PVVEiz-MZkwI2icqLn1RJaS84MANVmiCYq8geIlKsq-K/yrtHTxyXTnF-WXmkZmwWeVt8AK7pyU7E06uv+cSWInqBh7q/yGrtNllwQqss33F5gXLpsyEm4KLcBZ8D2O4-7qXPfAM3YRgBey3ivD5tZTq1-lY8ENIRki~4v6q3bLKHar/aR+0wL8QX+UlFqdOyzNIJ0nhyO5w_7_5Fb_xb4h9VeLc479EPO3X9B_JX09LNcTR例えば、Bearer認証を使用して、レコードのリストを取得するためのcURLコマンドは、以下のようになります。
curl -H 'Authorization: Bearer t2fde9481edc1a2be612c563d52619b3825f77ff757f16dfcff1d414874731594.S7HAvwFqCUexNe7~PVVEiz-MZkwI2icqLn1RJaS84MANVmiCYq8geIlKsq-K/yrtHTxyXTnF-WXmkZmwWeVt8AK7pyU7E06uv+cSWInqBh7q/yGrtNllwQqss33F5gXLpsyEm4KLcBZ8D2O4-7qXPfAM3YRgBey3ivD5tZTq1-lY8ENIRki~4v6q3bLKHar/aR+0wL8QX+UlFqdOyzNIJ0nhyO5w_7_5Fb_xb4h9VeLc479EPO3X9B_JX09LNcTR' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records'Basic認証を使用して認証を行なうには、あなたのユーザーIDを認証のユーザー名として、パスワードを認証のパスワードとして使用してください。ユーザー名を認証のユーザー名として使用することはできません。
例えば、ベーシック認証を使用して、レコードのリストを取得するためのcURLコマンドは、以下のようになります。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records'シングルサインオンが有効な場合には、ベーシック認証は使用できません。
リクエストの最大サイズは100KBです。ただし、複数のレコードを挿入・更新するAPIにおいては、1MBです。また、添付ファイルを作成するAPIにおいては、添付ファイルの最大サイズになります。作成できる添付ファイルのサイズは、デフォルトでは50MBです。
リクエストが大きすぎると、INVALID_BODYエラーが返されます。
一定時間内に使用できるリクエストの回数には、いくつかの制限があります。以下が現在の制限ですが、これらは変更される可能性があります。これらの制限は、アプリケーション単位で適用されます。
| API | Premiumプランの制限 | Enterpriseプランの制限 |
|---|---|---|
| レコードリスト・レコード・ユーザーリスト・アプリケーション定義の取得 | 1時間あたり4,000リクエスト | 1時間あたり8,000リクエスト |
| レコードの作成・更新・削除、プッシュ通知の送信 | 1時間あたり2,000リクエスト | 1時間あたり4,000リクエスト |
| 添付ファイルの取得 | 1時間あたり500リクエスト | 1時間あたり1,000リクエスト |
| 添付ファイルの作成 | 1時間あたり100リクエスト | 1時間あたり200リクエスト |
これらの制限は、同じグループ内の全てのリクエストに適用されます。例えば、1時間以内に3,900回レコードのリストを取得すると、この期間内には後100回しかユーザーを取得できません。回数制限は毎時リセットされます。
リクエスト回数が制限に達すると、429ステータスコードと共に、TOO_MANY_REQUESTSエラーレスポンスが返されます。
この章では、いくつかの例を挙げて、どのようにPlatio APIを使うのかを説明します。詳細については、Platio API リファレンスを参照してください。
コレクション内のレコードのリストを取得するには、GETリクエストを使用します。このAPIは、指定されたコレクションの最初の100レコードを返します。レコードは、更新日時で降順にソートされます。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records'次の100レコードを取得するには、skipパラメーターを使用します。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records?skip=100'全てのレコードを取得するには、skipパラメーターを増やしながら、レコードが返されなくなるまで繰り返しこのAPIを呼び出します。
limitパラメーターを使用して、取得するレコードの数を指定することもできます。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records?skip=100&limit=30'レコードを検索したりソートすることもできます。例えば、以下の例では、検索条件にあうレコードを、名前カラムの昇順で取得しています。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records?search=Name:foo&sortKey=column&sortColumnId=c002c2c0&sortOrder=ascending'レコードは、作成日時、更新日時、作成者、更新者、または特定のカラムの値でソートすることができます。カラムの値でレコードをソートするには、そのカラムをソート可能にする必要があります。
カラムでソートしたときに、どのようにレコードがソートされるかは、カラムの型に寄ります。詳細は、型と値を参照してください。
これらのパラメーターの詳細については、Platio API リファレンスを参照してください。また、検索条件については、レコード検索書式を参照してください。
このAPIは、レコードの配列を返します。
[
{
"id": "ri5f3cykexfbkzk7ohzqm2oocni",
"createdAt": "2016-07-20T11:39:50.007Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-20T11:39:50.007Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "3a73153a4a7abc176a3fa5dd538b8bda41e9d68d",
"timestamp": "2016-07-20T11:39:50.050Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "My Name"
},
"cfe0266a": {
"type": "Attachment",
"id": "ac2lzz2afdvguze5znhselxd4oe",
"contentType": "image/jpeg",
"name": "image.jpeg",
"size": 254179
},
"c915a0bc": {
"type": "Number",
"value": 28
}
}
},
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
}
]条件に合致するレコードがない場合には、空の配列を返します。
レコードを取得するには、レコードに対してGETリクエストを使用します。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records/ri5f3cykexfbkzk7ohzqm2oocni'このAPIは、指定されたレコードを返します。
{
"id": "ri5f3cykexfbkzk7ohzqm2oocni",
"createdAt": "2016-07-20T11:39:50.007Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-20T11:39:50.007Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "3a73153a4a7abc176a3fa5dd538b8bda41e9d68d",
"timestamp": "2016-07-20T11:39:50.050Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "My Name"
},
"cfe0266a": {
"type": "Attachment",
"id": "ac2lzz2afdvguze5znhselxd4oe",
"contentType": "image/jpeg",
"name": "image.jpeg",
"size": 254179
},
"c915a0bc": {
"type": "Number",
"value": 28
}
}
}レコードを作成するには、POSTリクエストを使用します。
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: application/json' \
-d '{"values":{"c002c2c0":{"type":"String","value":"Scott Tiger"}}}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records'リクエスト本体には、valuesプロパティを含む必要があります。このプロパティには、カラムIDから値へのマッピングを指定します。詳細については、型と値を参照してください。
このAPIは、作成されたレコードを返します。
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
}アプリケーションの管理者ユーザーは、オプションのcreatorIdプロパティを指定することができます。このプロパティにユーザーIDを指定すると、作成されたレコードの作成者が、あなたではなく指定したユーザーになります。他のユーザーのIDは、ユーザーリストを取得するAPIで取得できます。
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: application/json' \
-d '{"values":{"c002c2c0":{"type":"String","value":"Scott Tiger"}},"creatorId":"u7ecc403"}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records'作成されたレコードのcreatedByとupdatedByは、指定されたユーザーになります。
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "u7ecc403",
name: "user2"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "u7ecc403",
name: "user2"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
}複数のレコードを作成するには、POSTリクエストを使用します。一つのレコードを作成するときと同じURLですが、一つのJSONオブジェクトの代わりに、JSONオブジェクトの配列を渡します。一回のリクエストで、最大100個のレコードが作成できます。
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: application/json' \
-d '[{"values":{"c002c2c0":{"type":"String","value":"Scott Tiger"}}},{"values":{"c002c2c0":{"type":"String","value":"Mike Deer"}}}]' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records'このAPIは、作成されたレコードを配列で返します。
[
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
},
{
"id": "rt5yjwvcfznel5jql73pxn7rz5u",
"createdAt": "2016-08-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-08-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "3d6d2537a343d3a82be6141858165fc0768dc941",
"timestamp": "2016-08-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Mike Deer"
}
}
}
]アプリケーションの管理者ユーザーは、各レコードに、オプションのcreatorIdプロパティを指定して、レコードの作成者を指定することができます。レコードの作成者を指定する場合、全てのレコードの作成者を指定する必要があります。
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: application/json' \
-d '[{"values":{"c002c2c0":{"type":"String","value":"Scott Tiger"}},"creatorId":"u7ecc403"},{"values":{"c002c2c0":{"type":"String","value":"Mike Deer"}},"creatorId":"uf598c3f"}]' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records'複数のレコードを作成した場合、途中のレコードの作成中にエラーが発生することがあります。例えば、重複不可のカラムの値が重複した場合などです。この場合、エラーが発生したレコードの直前のレコードまでが作成されます。また、エラーレスポンスには、エラーが発生するまでに作成されたレコードの情報が含まれます。
{
"code": "DUPLICATED_VALUES",
"params": {
"duplicatedValues": [
{
"columnId": "c002c2c0",
"value": "Mike Deer",
}
],
"recordIndex": 1,
"insertedRecords": [
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
}
]
}
}既に存在するレコードを更新するには、レコードに対してPUTリクエストを使用します。
curl -u uf598c3f:mypassword \
-X PUT \
-H 'Content-Type: application/json' \
-d '{"values":{"c002c2c0":{"type":"String","value":"Jeff Scott"}}}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records/ri5f3cykexfbkzk7ohzqm2oocni'リクエスト本体には、valuesプロパティを含む必要があります。このプロパティには、カラムIDから値へのマッピングを指定します。詳細については、型と値を参照してください。
このAPIは、デフォルトでは、レコードの全ての値を置き換えます。カラムの値を指定しないと、そのカラムの元の値は削除されます。
valuesプロパティで指定した値だけを置き換えたい場合には、replaceプロパティにfalseを指定します。値を削除したい場合には、値としてnullを指定します。
curl -u uf598c3f:mypassword \
-X PUT \
-H 'Content-Type: application/json' \
-d '{"values":{"c002c2c0":{"type":"String","value":"Jeff Scott"},"c915a0bc":null},"replace":false}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records/ri5f3cykexfbkzk7ohzqm2oocni'このAPIは、更新されたレコードを返します。
{
"id": "ri5f3cykexfbkzk7ohzqm2oocni",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-08-14T01:43:10.165Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-08-14T01:43:10.254Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Jeff Scott"
}
}
}既に存在する複数のレコードを更新するには、PUTリクエストを使用します。一回のリクエストで、最大100個のレコードが更新できます。
curl -u uf598c3f:mypassword \
-X PUT \
-H 'Content-Type: application/json' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records' \
-d @- <<'EOF'
[
{
"id":"ri5f3cykexfbkzk7ohzqm2oocni",
"values": {
"c002c2c0": {
"type": "String",
"value": "Jeff Scott"
}
}
},
{
"id":"rw5zevfgfnne4zoj4sxbbkew4la",
"values": {
"c002c2c0": {
"type": "String",
"value": "Mike Deer"
}
}
}
]
EOFリクエスト本体には、オブジェクトの配列を指定し、各オブジェクトは、idとvaluesプロパティを含む必要があります。idプロパティには、更新するレコードのIDを指定します。valuesプロパティには、カラムIDから値へのマッピングを指定します。詳細については、型と値を参照してください。
このAPIは、レコードの更新と同じように、レコードの全ての値を置き換えます。カラムの値を指定しないと、そのカラムの元の値は削除されます。
valuesプロパティで指定した値だけを置き換えたい場合には、replaceプロパティにfalseを指定します。値を削除したい場合には、値としてnullを指定します。
curl -u uf598c3f:mypassword \
-X PUT \
-H 'Content-Type: application/json' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records' \
-d @- <<'EOF'
[
{
"id":"ri5f3cykexfbkzk7ohzqm2oocni",
"values": {
"c002c2c0": {
"type": "String",
"value": "Jeff Scott"
},
"c915a0bc":null
},
"replace":false
},
{
"id":"rw5zevfgfnne4zoj4sxbbkew4la",
"values": {
"c002c2c0": {
"type": "String",
"value": "Mike Deer"
},
"c915a0bc": null
},
"replace": false
}
]
EOFこのAPIは、更新されたレコードを配列で返します。
[
{
"id": "ri5f3cykexfbkzk7ohzqm2oocni",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-08-14T01:43:10.165Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-08-14T01:43:10.254Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Jeff Scott"
}
}
},
{
"id": "rt5yjwvcfznel5jql73pxn7rz5u",
"createdAt": "2016-08-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-08-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "3d6d2537a343d3a82be6141858165fc0768dc941",
"timestamp": "2016-08-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Mike Deer"
}
}
}
]複数のレコードを更新した場合、途中のレコードの更新中にエラーが発生することがあります。例えば、重複不可のカラムの値が重複した場合などです。この場合、エラーが発生したレコードの直前のレコードまでが更新されます。また、エラーレスポンスには、エラーが発生するまでに更新されたレコードの情報が含まれます。
{
"code": "DUPLICATED_VALUES",
"params": {
"duplicatedValues": [
{
"columnId": "c002c2c0",
"value": "Mike Deer",
}
],
"recordIndex": 1,
"updatedRecords": [
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
}
]
}
}レコードをUpsertするには、PATCHリクエストを使用します。キーとなるカラムのIDはURLの最後に指定します。指定されたレコードのキーカラムの値で既存のレコードを検索し、レコードが見つかった場合にはそのレコードを更新します。見つからなかった場合には、新規にレコードを作成します。
以下の例では、IDがc002c2c0のカラムの値がScott Tigerであるようなレコードが既にあれば、そのレコードを指定された値で更新し、ない場合には指定された値を持つレコードを作成します。
curl -u uf598c3f:mypassword \
-X PATCH \
-H 'Content-Type: application/json' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records/upsert/c002c2c0' \
-d @- <<'EOF'
{
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
},
"cf598c3f": {
"type": "Number",
"value": 5
}
}
}
EOFリクエスト本体には、valuesプロパティを含む必要があります。このプロパティには、カラムIDから値へのマッピングを指定します。詳細については、型と値を参照してください。
valuesプロパティには、必ずキーカラムに適切な値を指定する必要があります。指定されていない場合、MISSING_UPSERT_KEY_VALUEエラーが返されます。
レコードを更新する場合には、valuesプロパティで指定した値だけを置き換えます。つまり、レコードの更新のreplaceパラメーターがfalseであるのと同様に振舞います。
このAPIは、更新・作成されたレコードを返します。
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
}アプリケーションの管理者ユーザーは、オプションのcreatorIdプロパティを指定することができます。このプロパティにユーザーIDを指定すると、レコードが作成される場合、そのレコードの作成者が、あなたではなく指定したユーザーになります。他のユーザーのIDは、ユーザーリストを取得するAPIで取得できます。
curl -u uf598c3f:mypassword \
-X PATCH \
-H 'Content-Type: application/json' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records/upsert/c002c2c0' \
-d @- <<'EOF'
{
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
},
"cf598c3f": {
"type": "Number",
"value": 5
}
},
"creatorId": "u7ecc403"
}
EOF作成されたレコードのcreatedByとupdatedByは、指定されたユーザーになります。
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "u7ecc403",
name: "user2"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "u7ecc403",
name: "user2"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
}複数のレコードをUpsertするには、PATCHリクエストを使用します。一つのレコードをUpsertするときと同じURLですが、一つのJSONオブジェクトの代わりに、JSONオブジェクトの配列を渡します。一回のリクエストで、最大100個のレコードがUpsertできます。
Upsertの動作については、レコードのUpsertを参照してください。
curl -u uf598c3f:mypassword \
-X PATCH \
-H 'Content-Type: application/json' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records/upsert/c002c2c0' \
-d @- <<'EOF'
[
{
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
},
{
"values": {
"c002c2c0": {
"type": "String",
"value": "Mike Deer"
}
}
}
]
EOFこのAPIは、更新・作成されたレコードを配列で返します。
[
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
},
{
"id": "rt5yjwvcfznel5jql73pxn7rz5u",
"createdAt": "2016-08-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-08-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "3d6d2537a343d3a82be6141858165fc0768dc941",
"timestamp": "2016-08-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Mike Deer"
}
}
}
]アプリケーションの管理者ユーザーは、各レコードに、オプションのcreatorIdプロパティを指定して、レコードの作成者を指定することができます。レコードの作成者を指定する場合、全てのレコードの作成者を指定する必要があります。
curl -u uf598c3f:mypassword \
-X PATCH \
-H 'Content-Type: application/json' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records/upsert/c002c2c0' \
-d @- <<'EOF'
[
{
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
},
"creatorId": "u7ecc403"
},
{
"values": {
"c002c2c0": {
"type": "String",
"value": "Mike Deer"
}
},
"creatorId": "uf598c3f"
}
]
EOF複数のレコードを作成した場合、途中のレコードの作成中にエラーが発生することがあります。例えば、重複不可のカラムの値が重複した場合などです。この場合、エラーが発生したレコードの直前のレコードまでがUpsertされます。また、エラーレスポンスには、エラーが発生するまでにUpsertされたレコードの情報が含まれます。
{
"code": "DUPLICATED_VALUES",
"params": {
"duplicatedValues": [
{
"columnId": "c002c2c0",
"value": "Mike Deer",
}
],
"recordIndex": 1,
"upsertedRecords": [
{
"id": "rw5zevfgfnne4zoj4sxbbkew4la",
"createdAt": "2016-07-28T15:12:10.043Z",
"createdBy": {
id: "uf598c3f",
name: "user1"
},
"updatedAt": "2016-07-28T15:12:10.043Z",
"updatedBy": {
id: "uf598c3f",
name: "user1"
},
"hash": "8f935ee46a603cbbf36c65f1c34653cfb27f199a",
"timestamp": "2016-07-28T15:12:10.514Z",
"values": {
"c002c2c0": {
"type": "String",
"value": "Scott Tiger"
}
}
}
]
}
}既に存在するレコードを削除するには、レコードに対してDELETEリクエストを使用します。
curl -u uf598c3f:mypassword \
-X DELETE \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records/ri5f3cykexfbkzk7ohzqm2oocni'このAPIは、204ステータスコードと共に空のレスポンスを返します。
複数のレコードをまとめて削除するには、DELETEリクエストを使用します。
curl -u uf598c3f:mypassword \
-X DELETE \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records'検索条件にあうレコードを削除するには、searchパラメーターを指定します。
curl -u uf598c3f:mypassword \
-X DELETE \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/records?search=Name:foo'limitパラメーターを指定すると、削除するレコードの最大数を指定することができます。大量のレコードを一度に削除すると、時間がかかりすぎてリクエストがタイムアウトすることがあります。そのような場合には、適切なlimitパラメーターを指定して複数回リクエストを送ることで、全てのレコードを削除することができます。
パラメーターの詳細については、Platio API リファレンスを参照してください。また、検索条件については、レコード検索書式を参照してください。
このAPIは、limitを指定しない場合には、204ステータスコードと共に空のレスポンスを返します。また、limitを指定した場合には、200ステータスコードと共に削除したレコード数を返します。
{
"deletedCount": 5345
}このAPIがエラーを返した場合でも、一部のレコードは削除されている可能性があります。
添付ファイルを取得するには、添付ファイルに対してGETリクエストを使用します。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/attachments/ac2lzz2afdvguze5znhselxd4oe'レスポンスは、添付ファイル本体です。添付ファイルのContent-Typeと名前は、Content-TypeとContent-Dispositionヘッダから取得することができます。
添付ファイルは、その添付ファイルを参照するレコードが存在しても、まだ取得できないことがあることに注意してください。これは、添付ファイルはレコードとは別に非同期にアップロードされるためです。このAPIから404レスポンスが返された場合、ある程度の時間をおいて再度取得してください。添付ファイルを取得できるようになるまで、数秒から数日かかる可能性があります。これは、添付ファイルをアップロードする前にPlatioアプリがオフラインになる可能性があるためです。
Attachment型の値を含むレコードを作成するときには、まず添付ファイルを先に作成します。POSTリクエストを使用することで、ファイルをアップロードし、添付ファイルのIDを取得できます。このIDを、レコードを作成するときに使用します。
ファイルをアップロードするときには、Content-TypeとContent-Dispositionヘッダを指定するのを忘れないでください。
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: image/jpeg' \
-H 'Content-Disposition: attachment; filename=image.jpeg' \
--data-binary @image.jpeg \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/attachments'この例では、カレントディレクトリにimage.jpgがあることを想定しています。
アプリケーションの管理者ユーザーは、オプションのX-Platio-CreatorIdヘッダーを指定することができます。このヘッダーにユーザーIDを指定すると、作成された添付ファイルの作成者が、あなたではなく指定したユーザーになります。他のユーザーのIDは、ユーザーリストを取得するAPIで取得できます。
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: image/jpeg' \
-H 'Content-Disposition: attachment; filename=image.jpeg' \
-H 'X-Platio-CreatorId: u7ecc403' \
--data-binary @image.jpeg \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/collections/tf71dbb9/attachments'アプリケーションのユーザリストを取得するには、GETリクエストを使用します。このAPIは、アプリケーションの最初の100ユーザーを返します。ユーザーは、名前で昇順にソートされます。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/users'次の100ユーザーを取得するには、skipパラメーターを使用します。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/users?skip=100'全てのユーザーを取得するには、skipパラメーターを増やしながら、ユーザーが返されなくなるまで繰り返しこのAPIを呼び出します。
limitパラメーターを使用して、取得するユーザーの数を指定することもできます。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/users?skip=100&limit=30'返されるユーザーを絞り込むには、searchパラメーターを使用します。名前が指定された値を含むユーザーが返されます。名前は大文字小文字を区別して比較されます。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/users?search=user'このAPIは、ユーザーの配列を返します。
[
{
"id": "uf598c3f",
"name": "user1"
},
{
"id": "u7ecc403",
"name": "user2"
}
]返されたユーザーをUser型の値で使用したり、レコードの作成者としてIDを使用することができます。
APIを使用して、ユーザーのPlatioアプリにプッシュ通知を送ることができます。プッシュ通知を送るには、アプリケーションの設定でプッシュ通知を有効にしてください。また、ミニアプリの管理者ユーザーのみがプッシュ通知を送ることができます。
curl -u uf598c3f:mypassword \
-X POST \
-H 'Content-Type: application/json' \
-d '{"title":"Warning!","body":"The temperature is too high.","sound":"default"}' \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/users/uf598c3f/notifications'titleプロパティにには通知のタイトルを、bodyプロパティには本文を指定します。それぞれ、128文字、512文字以内の文字列を指定できます。
1024文字以内のURLをurlプロパティに指定すると、ユーザーが通知をタップした時にそのURLを開きます。URLとして、Platio
URLを指定することで、通知をタップした時に指定したデータポケットやレコードを表示することもできます。
soundプロパティにdefaultを指定すると、通知時に音を鳴らすことができます。音を鳴らさない場合には、このプロパティを指定しないでください。
このAPIは、204ステータスコードと共に空のレスポンスを返します。
通知が成功しても、ユーザーが通知を受け取らない可能性があることに注意してください。例えば、ユーザーがミニアプリからログアウトしていたり、デバイスの設定で通知を受け取らないようにしている場合、ユーザーは通知を受け取りません。
アプリケーションの定義を取得するには、GETリクエストを使用します。
curl -u uf598c3f:mypassword \
'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa'このAPIは、コレクションとカラムの定義を含む、アプリケーションの定義を返します。返されるオブジェクトの詳細については、Platio API リファレンスを参照してください。
{
"id": "pkyfjjjmlyffnlgeb5oh2eqs2aa",
"version": 7,
"name": "Sample",
"sharedUsersModeEnabled": false,
"teamsModeEnabled": false,
"url": "https://app.plat.io/app/Demo/Sample",
"collections": [
{
"id": "tf71dbb9",
"name": "Sample",
"readAccessType": "everyone",
"writeAccessType": "creatorOnly",
"columns": [
{
"id": "c002c2c0",
"name": "Name",
"type": "String",
"unique": false,
"sortable": true,
"searchable": true
},
{
"id": "cfe0266a",
"name": "Photo",
"type": "Attachment",
"unique": false,
"sortable": false,
"searchable": false
},
{
"id": "c915a0bc",
"name": "Age",
"type": "Number",
"unique": false,
"sortable": false,
"searchable": true
}
]
}
]
}何か問題が発生すると、Platio APIはエラーを返します。エラーは、HTTPステータスコードと、エラーコードを含むJSON形式のレスポンスで返されます。
認証のエラーは401ステータスコードを返します。リクエストに問題がある場合には、400または404ステータスコードを返します。サーバー上で問題が発生した場合には、500または503ステータスコードを返します。
エラーコードに関する詳細は、Platio API エラーを参照してください。