Platio 管理API プログラミングガイド

Platio 管理APIは、Platio APIの一部で、プログラミングを通して、Platio Studioで作成したミニアプリのユーザーなどを操作するためのWeb APIです。

このドキュメントは、Platio API プログラミングガイドに目を通していることを前提としています。まだ、ご覧になっていない場合は、まずそちらをご覧ください。

概要

準備

Platio 管理APIを利用するには、アプリケーションを作成し、配布する必要あります。配布したアプリケーションに管理APIがアクセスできるユーザーを追加してください。ユーザーを作成、更新する時に、「APIでのレコードや添付ファイルへのアクセスを許可」に加えて、「APIでのユーザーの管理を許可 (管理API)」の両方をチェックします。また、共通ユーザーを管理するには、さらに「APIでの共通ユーザーの管理を許可 (組織管理API)」もチェックしてください。

APIのエンドポイントや、認証方法などについては、Platio API プログラミングガイドをご覧ください。

制限

リクエスト回数以外のAPIの制限については、Platio API プログラミングガイドをご覧ください。

リクエスト回数

一定時間内に使用できるリクエストの回数には、いくつかの制限があります。以下が現在の制限ですが、これらは変更される可能性があります。これらの制限は、アプリケーション単位で適用されます。

API	Premiumプランの制限	Enterpriseプランの制限
ユーザーリスト・ユーザー・共通ユーザーリスト・共通ユーザーの取得	N/A	1時間あたり2,000リクエスト
ユーザー・共通ユーザーの作成・更新・削除	N/A	1時間あたり1,000リクエスト

これらの制限は、同じグループ内の全てのリクエストに適用されます。回数制限は毎時リセットされます。

リクエスト回数が制限に達すると、429ステータスコードと共に、TOO_MANY_REQUESTSエラーレスポンスが返されます。

Platio 管理APIを使う

この章では、いくつかの例を挙げて、どのようにPlatio 管理APIを使うのかを説明します。詳細については、Platio API リファレンスをご覧ください。

ユーザーの操作

ユーザーの操作を行うAPIでは、共通ユーザー機能が有効かどうか、チーム機能が有効かどうかによって、APIで行える操作、APIに渡す情報、APIから返される情報が異なる事があります。操作対象の組織・アプリケーションの設定をご確認の上、ご利用ください。

ユーザーリストの取得

ユーザーのリストを取得するには、GETリクエストを使用します。このAPIは、アプリケーションの最初の100ユーザーを、名前で昇順にソートして返します。

curl -u uf598c3f:mypassword \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users'

次の100ユーザーを取得するには、skipパラメーターを使用します。

curl -u uf598c3f:mypassword \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users?skip=100'

全てのユーザーを取得するには、skipパラメーターを増やしながら、空の配列が返されるまで、繰り返しこのAPIを呼び出します。

また、limitパラメーターを使用して、取得するユーザー数を指定することもできます。

curl -u uf598c3f:mypassword \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users?limit=30'

ユーザーを検索することもできます。searchパラメーターに文字列を指定すると、ユーザーの名前・メールアドレス・プロファイル名・チーム名に、指定した文字列が、大文字・小文字を区別せずに含まれるユーザーを返します。

共通ユーザー機能が有効な場合、指定したアプリケーションで設定済みのユーザーのみを返すことに注意してください。

このAPIは、ユーザーのリストを返します。

[
  {
    "id": "u37367df",
    "name": "User",
    "email": "user@example.com",
    "admin": false,
    "apiAccess": true,
    "managementApiAccess": true,
    "organizationManagementApiAccess": false,
    "profile": {
      "name": "デフォルト"
    },
    "disabled": false
  },
  {
    "id": "u2cc0613",
    "name": "User2",
    "email": "user2@example.com",
    "admin": false,
    "apiAccess": false,
    "managementApiAccess": false,
    "organizationManagementApiAccess": false,
    "profile": {
      "name": "デフォルト"
    },
    "disabled": false
  }
]

チーム機能が有効な場合には、各ユーザーのチームの情報が含まれます。

[
  {
    "id": "u4d6a6dd",
    "name": "User",
    "email": "user@example.com",
    "admin": false,
    "apiAccess": true,
    "managementApiAccess": true
    "organizationManagementApiAccess": false,
    "profile": {
      "name": "デフォルト"
    },
    "team": {
      "name": "デフォルト"
    },
    "teamLeader": false,
    "disabled": false
  },
  {
    "id": "u1ee8203",
    "name": "User2",
    "email": "user2@example.com",
    "admin": false,
    "apiAccess": true,
    "managementApiAccess": true,
    "organizationManagementApiAccess": false,
    "profile": {
      "name": "デフォルト"
    },
    "team": {
      "name": "デフォルト"
    },
    "teamLeader": false,
    "disabled": false
  }
]

ユーザーの取得

ユーザーを取得するには、ユーザーに対してGETリクエストを使用します。

curl -u uf598c3f:mypassword \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'

このAPIは、指定されたユーザーを返します。

{
  "id": "u37367df",
  "name": "User",
  "email": "user@example.com",
  "admin": false,
  "apiAccess": true,
  "managementApiAccess": true,
  "organizationManagementApiAccess": false,
  "profile": {
    "name": "デフォルト"
  },
  "disabled": false
}

チーム機能が有効な場合には、チームの情報が含まれます。

{
  "id": "u37367df",
  "name": "User",
  "email": "user@example.com",
  "admin": false,
  "apiAccess": true,
  "managementApiAccess": true,
  "organizationManagementApiAccess": false,
  "profile": {
    "name": "デフォルト"
  },
  "team": {
    "name": "デフォルト"
  },
  "teamLeader": false,
  "disabled": false
}

ユーザーの作成

ユーザーを作成するには、POSTリクエストを使用します。

共通ユーザー機能が無効な場合には、以下のようなリクエストを使用します。

curl -u uf598c3f:mypassword \
     -X POST \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "User3",
           "email": "user3@example.com",
           "password": "Abcd1234",
           "admin": false,
           "apiAccess": true,
           "managementApiAccess": false,
           "profile": {
             "name": "デフォルト"
           }
         }' \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users'

チーム機能が有効な場合には、チームの情報を含めます。

curl -u uf598c3f:mypassword \
     -X POST \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "User3",
           "email": "user3@example.com",
           "password": "Abcd1234",
           "admin": false,
           "apiAccess": true,
           "managementApiAccess": false,
           "profile": {
             "name": "デフォルト"
           },
           "team": {
             "name": "デフォルト"
           },
           "teamLeader: true
         }' \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users'

organizationManagementApiAccess以外の、すべてのプロパティを指定する必要があります。また、プロファイルやチームは名前で指定します。

プロパティによっては、指定できる値に制限があります。

1. nameプロパティには、1文字以上64文字以下で、「_」から始まらない文字列を指定します。
2. passwordプロパティには、8文字以上の、小文字、大文字、数字をすべて1文字以上含む文字列を指定します。
3. profile.nameプロパティには、存在するプロファイルの名前を指定します。
4. team.nameプロパティには、存在するチームの名前を指定します。

共通ユーザー機能が有効な場合には、このAPIは、新しいユーザーを作成する代わりに、既存の共通ユーザーをこのアプリケーションで設定します。そのため、呼び出し方にいくつかの違いがあります。

1. nameプロパティには、既存の、このアプリケーションで未設定な共通ユーザーの名前を指定します。
2. password, emailプロパティは指定できません。

curl -u uf598c3f:mypassword \
     -X POST \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "User3",
           "admin": false,
           "apiAccess": true,
           "managementApiAccess": false,
           "profile": {
             "name": "デフォルト"
           }
         }' \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users'

このAPIは作成したユーザーを返します。

{
  "id": "u37367df",
  "name": "User3",
  "email": "user3@example.com",
  "admin": false,
  "apiAccess": true,
  "managementApiAccess": false,
  "organizationManagementApiAccess": false,
  "profile": {
    "name": "デフォルト"
  },
  "disabled": false
}

チーム機能が有効な場合には、チームの情報が含まれます。

{
  "id": "u37367df",
  "name": "User",
  "email": "user@example.com",
  "admin": false,
  "apiAccess": true,
  "managementApiAccess": false,
  "organizationManagementApiAccess": false,
  "profile": {
     "name": "デフォルト"
  },
  "team": {
     "name": "デフォルト"
  },
  "teamLeader": false,
  "disabled": false
}

ユーザーの更新

既に存在するユーザーを更新するには、ユーザーに対してPUTリクエストを使用します。

curl -u uf598c3f:mypassword \
     -X PUT \
     -H 'Content-Type: application/json' \
     -d '{
           "email": "new-email@example.com",
           "admin": true,
           "apiAccess": true,
           "managementApiAccess": false,
           "profile": {
             "name": "デフォルト"
           },
           "disabled": false
         }' \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'

チーム機能が有効な場合には、チームの情報を含めます。

curl -u uf598c3f:mypassword \
     -X PUT \
     -H 'Content-Type: application/json' \
     -d '{
           "email": "new-email@example.com",
           "admin": true,
           "apiAccess": true,
           "managementApiAccess": false,
           "profile": {
             "name": "デフォルト"
           },
           "team": {
             "name": "デフォルト"
           },
           "teamLeader: true,
           "disabled": false
         }' \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'

passwordとorganizationManagementApiAccess以外の、すべてのプロパティを指定する必要があります。また、プロファイルやチームは名前で指定します。

共通ユーザー機能が有効な場合には、呼び出し方にいくつかの違いがあります。

1. password, emailプロパティは指定できません。

curl -u uf598c3f:mypassword \
     -X PUT \
     -H 'Content-Type: application/json' \
     -d '{
           "admin": true,
           "apiAccess": true,
           "managementApiAccess": false,
           "profile": {
             "name": "デフォルト"
           },
           "disabled": false
         }' \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'

このAPIは更新したユーザーを返します。

{
  "id": "u37367df",
  "name": "User",
  "email": "new-email@example.com",
  "admin": true,
  "apiAccess": true,
  "managementApiAccess": false,
  "organizationManagementApiAccess": false,
  "profile": {
    "name": "デフォルト"
  },
  "disabled": false
}

チーム機能が有効な場合には、チームの情報が含まれます。

{
  "id": "u37367df",
  "name": "User",
  "email": "new-email@example.com",
  "admin": true,
  "apiAccess": true,
  "managementApiAccess": false,
  "organizationManagementApiAccess": false,
  "profile": {
    "name": "デフォルト"
  },
  "team": {
    "name": "デフォルト"
  },
  "teamLeader": false,
  "disabled": false
}

ユーザーの削除

既に存在するユーザーを削除するには、ユーザーに対してDELETEリクエストを使用します。

共通ユーザー機能が有効な場合には、このAPIは使用できません。

curl -u uf598c3f:mypassword \
     -X DELETE \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/users/u37367df'

このAPIは、204ステータスコードと共に空のレスポンスを返します。

共通ユーザーの操作

共通ユーザーを操作するAPIを使用すると、呼び出し元のアプリケーションが属する組織の共通ユーザーを取得したり更新する事ができます。これらのAPIは、共通ユーザー機能が有効な場合にのみ使用する事ができます。操作対象の組織の設定をご確認の上、ご利用ください。

共通ユーザーを管理するには、APIを呼び出すユーザーの設定で、「APIでの共通ユーザーの管理を許可 (組織管理API)」をチェックする必要があります。

共通ユーザーリストの取得

共通ユーザーのリストを取得するには、GETリクエストを使用します。このAPIは、最初の100共通ユーザーを、名前で昇順にソートして返します。

curl -u uf598c3f:mypassword \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers'

次の100共通ユーザーを取得するには、skipパラメーターを使用します。

curl -u uf598c3f:mypassword \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers?skip=100'

全ての共通ユーザーを取得するには、skipパラメーターを増やしながら、空の配列が返されるまで、繰り返しこのAPIを呼び出します。

また、limitパラメーターを使用して、取得する共通ユーザー数を指定することもできます。

curl -u uf598c3f:mypassword \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers?limit=30'

共通ユーザーを検索することもできます。searchパラメーターに文字列を指定すると、ユーザーの名前・メールアドレスに、指定した文字列が、大文字・小文字を区別せずに含まれるユーザーを返します。

このAPIは、共通ユーザーのリストを返します。

[
  {
    "id": "ucyhe5rnilvbcvd5336lvp7szay",
    "name": "User",
    "email": "user@example.com",
    "disabled": false
  },
  {
    "id": "umeyumwmfsfbzjbo3gr5tsc5ukm",
    "name": "User2",
    "email": "user2@example.com",
    "disabled": false
  }
]

共通ユーザーの取得

ユーザーを取得するには、共通ユーザーに対してGETリクエストを使用します。

curl -u uf598c3f:mypassword \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers/ucyhe5rnilvbcvd5336lvp7szay'

このAPIは、指定された共通ユーザーを返します。

{
  "id": "ucyhe5rnilvbcvd5336lvp7szay",
  "name": "User",
  "email": "user@example.com",
  "disabled": false
}

共通ユーザーの作成

共通ユーザーを作成するには、POSTリクエストを使用します。

curl -u uf598c3f:mypassword \
     -X POST \
     -H 'Content-Type: application/json' \
     -d '{
           "name": "User3",
           "email": "user3@example.com",
           "password": "Abcd1234"
         }' \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers'

すべてのプロパティを指定する必要があります。

プロパティによっては、指定できる値に制限があります。

1. nameプロパティには、1文字以上64文字以下で、「_」から始まらない文字列を指定します。
2. passwordプロパティには、8文字以上の、小文字、大文字、数字をすべて1文字以上含む文字列を指定します。

このAPIは作成した共通ユーザーを返します。

{
  "id": "u55ruf3stmjhzjjqmqkuirw4p34",
  "name": "User3",
  "email": "user3@example.com",
  "disabled": false
}

共通ユーザーの更新

既に存在する共通ユーザーを更新するには、共通ユーザーに対してPUTリクエストを使用します。

curl -u uf598c3f:mypassword \
     -X PUT \
     -H 'Content-Type: application/json' \
     -d '{
           "email": "new-email@example.com",
           "disabled": false
         }' \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers/ucyhe5rnilvbcvd5336lvp7szay'

password以外のすべてのプロパティを指定する必要があります。

このAPIは更新した共通ユーザーを返します。

{
  "id": "ucyhe5rnilvbcvd5336lvp7szay",
  "name": "User",
  "email": "new-email@example.com",
  "disabled": false
}

共通ユーザーの削除

既に存在する共通ユーザーを削除するには、共通ユーザーに対してDELETEリクエストを使用します。

curl -u uf598c3f:mypassword \
     -X DELETE \
     'https://api.plat.io/v1/pkyfjjjmlyffnlgeb5oh2eqs2aa/management/sharedUsers/ucyhe5rnilvbcvd5336lvp7szay'

このAPIは、204ステータスコードと共に空のレスポンスを返します。