ワークスペースコラボレーター
次のエンドポイントを使用して、ワークスペース内のコラボレーターを管理します。
APIクライアントアクセス
APIクライアントがコラボレーターを管理するには、DEVEnvironmentへのアクセスが必要です。 APIクライアントのアクセスを構成するには、クライアントロールを作成するを参照してください。
レート制限
ワークスペースコラボレーターリソースには、次のレート制限があります:
| タイプ | リソース | 制限 |
|---|---|---|
| POST | コラボレーターを招待: /api/member_invitations | 1分あたり60リクエスト さらに、このエンドポイントに、ユーザーおよびワークスペースIDごとに20分に1回リクエストを送信できます。 |
| すべて | その他すべてのワークスペースコラボレーターエンドポイント | 1分あたり60リクエスト |
クイックリファレンス
| タイプ | リソース | 説明 |
|---|---|---|
| POST | /api/member_invitations | コラボレーターをワークスペースに招待します。 |
| GET | /api/members | コラボレーターのリストを取得します。 |
| GET | /api/members/:id | コラボレーターの詳細を取得します。 |
| PUT | /api/members/:id | コラボレーターロールを更新します。 |
| DELETE | /api/members/:id | コラボレーターを削除します。 |
| GET | /api/members/:id/project_grants | コラボレーターのプロジェクト付与を一覧表示します。 |
| GET | /api/members/:id/privileges | コラボレーターの権限を取得します。 |
| GET | /api/members/:id/projects_privileges | コラボレーターのプロジェクト権限を取得します。 |
コラボレーターを招待する
コラボレーターをワークスペースに招待します。 指定したメールアドレスが既存のユーザーに属していない場合、APIはメール招待を送信します。 コラボレーターは、Workatoアカウントを作成した後でワークスペースに参加できます。 特定のメールアドレスとワークスペースの組み合わせは、20分に1回招待できます。
POST /api/member_invitationsリクエスト本文
| 名前 | タイプ | 説明 |
|---|---|---|
| name | string 必須 | コラボレーターの名前。 |
| string 必須 | コラボレーターのメールアドレス。 | |
| env_roles | object required | コラボレーターのEnvironmentロールを定義します。 |
| env_roles[environment_type] | string 必須 | コラボレーターを招待する予定のワークスペース内のEnvironmentのタイプ。 単一Environmentのワークスペースにはdevを使用します。 |
| env_roles[name] | string 必須 | 特定のEnvironmentに対してコラボレーターに割り当てるロール。 |
| env_roles[role_type] | string 任意 | コラボレーターに割り当てるロールのタイプ。 使用可能な値には、privilege_groupとenvironmentがあります。 デフォルト値はprivilege_groupです。 |
| role_name | string deprecated | このフィールドは非推奨です。 単一Environmentのワークスペースの場合でも、代わりにenv_rolesを使用します。 |
| user_group_ids | array of strings optional | 割り当てるコラボレーターグループのID。 |
サンプルリクエスト
- リクエスト1:
env_rolesを使用してコラボレーターを招待する - リクエスト2:
env_rolesを使用してコラボレーターを招待する: アクセスなし - リクエスト3: 存在しない、または利用できないロールでコラボレーターを招待する
- リクエスト4: 存在しないEnvironmentにコラボレーターを招待する
リクエスト1: env_rolesを使用してコラボレーターを招待する
このリクエスト例では、dev、test、prodEnvironmentの招待を作成します。 コラボレーターに、devEnvironmentではAdminロール、testEnvironmentではAnalystロール、prodEnvironmentではOperatorロールを割り当てます。
curl -X POST 'https://www.workato.com/api/member_invitations' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Josh",
"email": "[email protected]",
"user_group_ids": [
"am-WxEKCibh-dTXBtz",
"am-APNHJbmM-hfhTD8"
],
"env_roles": [
{
"environment_type": "dev",
"name": "Admin",
"role_type": "privilege_group"
},
{
"environment_type": "test",
"name": "Admin",
"role_type": "privilege_group"
},
{
"environment_type": "prod",
"name": "Admin",
"role_type": "privilege_group"
}
]
}'レスポンス1: env_rolesを使用してコラボレーターを招待する
{
"result": "ok"
}リクエスト2: env_rolesを使用してコラボレーターを招待する - アクセスなし
この例では、prodEnvironment専用の招待を作成します。 追加のEnvironmentとロールをenv_rolesオブジェクトから省略すると、デフォルトの動作により、その他すべてのEnvironmentでコラボレーターにNo accessロールが割り当てられます。
curl -X POST 'https://www.workato.com/api/member_invitations' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Josh",
"email": "[email protected]",
"user_group_ids": [
"am-WxEKCibh-dTXBtz",
"am-APNHJbmM-hfhTD8"
],
"env_roles": [
{
"environment_type": "prod",
"name": "Operator",
"role_type": "privilege_group"
}
]
}'レスポンス2: env_rolesを使用してコラボレーターを招待する - アクセスなし
{
"result": "ok"
}リクエスト3: 存在しない、または利用できないロールでコラボレーターを招待する
存在しない、または利用できないロールを使用してコラボレーターを招待すると、このエンドポイントは400エラーを返します: Role Not existing role not found。
curl -X POST 'https://www.workato.com/api/member_invitations' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Josh",
"email": "[email protected]",
"user_group_ids": [
"am-WxEKCibh-dTXBtz",
"am-APNHJbmM-hfhTD8"
],
"env_roles": [
{
"environment_type": "prod",
"name": "Not existing role",
"role_type": "privilege_group"
}
]
}'レスポンス3: 存在しない、または利用できないロールでコラボレーターを招待する
{
"message": "Role Not existing role not found"
}リクエスト4: 存在しないEnvironmentにコラボレーターを招待する
存在しないEnvironmentにコラボレーターを招待すると、このエンドポイントは400エラーを返します: Environment Not existing environment not found。
curl -X POST 'https://www.workato.com/api/member_invitations' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"name": "Josh",
"email": "[email protected]",
"user_group_ids": [
"am-WxEKCibh-dTXBtz",
"am-APNHJbmM-hfhTD8"
],
"env_roles": [
{
"environment_type": "Not existing environment",
"name": "Operator",
"role_type": "privilege_group"
}
]
}'レスポンス4: 存在しないEnvironmentにコラボレーターを招待する
{
"message": "Environment Not existing environment not found"
}コラボレーターのリストを取得する
ワークスペース内のすべてのコラボレーターのリストを取得します。 レスポンスには、主に2つの要素が含まれます:
| 要素 | 説明 |
|---|---|
data | それぞれがコラボレーターを表すオブジェクトの配列。 |
total | 返されたコラボレーターの合計数。 |
data配列内の各コラボレーターオブジェクトには、次の情報が含まれます:
| フィールド | 説明 |
|---|---|
id | ユーザーの一意の識別子。 |
grant_type | ユーザーの付与タイプ。 ワークスペースコラボレーターの場合はteam、ワークスペースモデレーターの場合はfederation_managerです。 |
user_groups | ユーザーに割り当てられたユーザーグループの配列。 |
roles | 異なるEnvironmentでユーザーに割り当てられたシステムロールまたはカスタムロールの配列。 |
last_activity_log | ワークスペースでのユーザーの最新アクティビティ。 AHQが有効なワークスペースでは、DEVEnvironmentでの最新のアクションのみが表示されます。 サインイン、トークン生成などのアクティビティが含まれます。 取得されるイベントの完全なリストについては、活動監査ログリファレンスを参照してください。 |
external_id | ユーザーの外部ID。 |
name | ユーザーの名前。 |
email | Workatoへのサインインに使用するユーザーのメールアドレス。 |
time_zone | ユーザーのタイムゾーン。 |
created_at | Workatoでユーザーが作成された日時。 |
エンドポイントアクセス
このエンドポイントを使用するには、APIクライアントロールにGet collaborators GET /api/members権限が割り当てられている必要があります。
GET /api/membersクエリパラメーター
| 名前 | タイプ | 説明 |
|---|---|---|
| string 任意 | 指定した値をメールアドレスに含むコラボレーターにリストをフィルタリングします。 特殊文字はURLエンコードする必要があります。 |
サンプルリクエスト
curl -X GET 'https://www.workato.com/api/members?email=example.com' \
-H 'Authorization: Bearer <api_token>'レスポンス
{
"data": [
{
"id": 12345,
"grant_type": "federation_manager",
"user_groups": [
{
"id": "am-WxEKCibh-dTXBtz",
"name": "All collaborators",
"system": true
},
{
"id": "am-WxEKCibh-dTXBtg",
"name": "Developers",
"system": false
}
],
"roles": [
{
"environment_type": "dev",
"role_name": "Admin",
"role_type": "privilege_group"
},
{
"environment_type": "test",
"role_name": "Admin",
"role_type": "privilege_group"
},
{
"environment_type": "prod",
"role_name": "Admin",
"role_type": "privilege_group"
}
],
"last_activity_log": {
"id": 2807129,
"event_type": "user_login",
"created_at": "2024-03-07T16:38:18.414-08:00"
},
"external_id": null,
"name": "Rosario",
"email": "[email protected]",
"time_zone": "Pacific Time (US & Canada)",
"created_at": "2021-12-14T13:01:15.935-08:00"
},
{
"id": 23456,
"grant_type": "team",
"user_groups": [
{
"id": "am-WxEKCibh-dTXBtz",
"name": "All collaborators",
"system": true
},
{
"id": "am-WxEKCibh-dTXBtg",
"name": "Developers",
"system": false
}
],
"roles": [
{
"environment_type": "dev",
"role_name": "IT_Developer",
"role_type": "privilege_group"
},
{
"environment_type": "test",
"role_name": "No access",
"role_type": "privilege_group"
},
{
"environment_type": "prod",
"role_name": "No access",
"role_type": "privilege_group"
}
],
"last_activity_log": {
"id": 2807129,
"event_type": "user_login",
"created_at": "2024-03-07T16:38:18.414-08:00"
},
"external_id": null,
"name": "Noam",
"email": "[email protected]",
"time_zone": "Pacific Time (US & Canada)",
"created_at": "2021-1-12T13:01:15.935-08:00"
}
],
"total": 2
}コラボレーターの詳細を取得する
指定したコラボレーターの詳細を取得します。 このリソースは、レスポンスで次の情報を返します:
- ユーザーID
- 付与タイプ:
teamはユーザーがワークスペースコラボレーターであることを示し、federation_managerはユーザーがワークスペースモデレーターであることを示します。 - ユーザーグループ
- ロール
- 外部ID
- 名前
- メール
- タイムゾーン
- 最新アクティビティログ: ワークスペース内でのユーザーの最新アクションを表示し、活動監査ログと同じデータを取得します。 AHQを使用しているワークスペースでは、DEVEnvironment内の最新アクティビティのみが表示されます。 ログイン、ログアウト、ワークスペースへの参加、トークンの生成、コネクションの切断などのイベントが含まれる場合があります。 ログで取得され、このリクエストで返される可能性があるアクティビティの完全なリストについては、活動監査ログリファレンスドキュメントを参照してください。
- 作成日時
GET /api/members/:idパスパラメーター
| 名前 | タイプ | 説明 |
|---|---|---|
| id | string 必須 | 取得するコラボレーターのID。 |
サンプルリクエスト
curl -X GET 'https://www.workato.com/api/members/34567' \
-H 'Authorization: Bearer <api_token>'レスポンス
{
"data": {
"id": 34567,
"grant_type": "team",
"user_groups": [
{
"id": "am-WxEKCibh-dTXBtz",
"name": "All collaborators",
"system": true
},
{
"id": "am-WxEKCibh-dTXBtg",
"name": "Developers",
"system": false
}
],
"roles": [
{
"environment_type": "dev",
"role_name": "HR_Developer",
"role_type": "privilege_group"
},
{
"environment_type": "test",
"role_name": "HR_Viewer",
"role_type": "privilege_group"
},
{
"environment_type": "prod",
"role_name": "Operator",
"role_type": "privilege_group"
}
],
"last_activity_log": {
"id": 2807147,
"event_type": "user_login",
"created_at": "2024-03-07T16:44:39.318-08:00"
},
"external_id": null,
"name": "Dana",
"email": "[email protected]",
"time_zone": "Pacific Time (US & Canada)",
"created_at": "2019-09-09T00:45:17.019-07:00"
}
}コラボレーターロールを更新する
既存のコラボレーターのロールをIDで更新します。 コラボレーターのアクセスを削除するには、リクエスト本文にNoAccessを含めます。
PUT /api/members/:idパスパラメーター
| 名前 | タイプ | 説明 |
|---|---|---|
| id | string 必須 | ロールを更新する予定のコラボレーターのID。 |
リクエスト本文
| 名前 | タイプ | 説明 |
|---|---|---|
| env_roles | object required | コラボレーターの更新後のEnvironmentロールを定義します。 |
| env_roles[environment_type] | string 必須 | コラボレーターのロールを更新する予定のワークスペースEnvironmentのタイプ。 単一Environmentのワークスペースにはdevを使用します。 |
| env_roles[name] | string 必須 | 特定のEnvironmentに対してコラボレーターに割り当てるロール。 |
| env_roles[role_type] | string 任意 | コラボレーターに割り当てるロールのタイプ。 使用可能な値には、privilege_groupとenvironmentがあります。 デフォルト値はprivilege_groupです。 |
サンプルリクエスト
- リクエスト1: 1つのEnvironmentでコラボレーターロールを更新する
- リクエスト2: すべてのEnvironmentでコラボレーターロールを更新する
- リクエスト3: 存在しない、または利用できないロールを使用してコラボレーターロールを更新する
- リクエスト4: 存在しないEnvironmentでコラボレーターロールを更新する
リクエスト1: 1つのEnvironmentでコラボレーターロールを更新する
このリクエスト例では、コラボレーターのロールをprodEnvironmentのOperatorに更新します。 他のEnvironmentのロールには影響しません。
curl -X PUT 'https://www.workato.com/api/members/34567' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"env_roles": [
{
"environment_type": "prod",
"name": "Operator",
"role_type": "privilege_group"
}
]
}'レスポンス1: 1つのEnvironmentでコラボレーターロールを更新する
{
"data": {
"result": "ok"
}
}リクエスト2: すべてのEnvironmentでコラボレーターロールを更新する
このリクエスト例では、コラボレーターのロールをprodEnvironmentのOperator、devEnvironmentのAdminに更新し、コラボレーターのtestEnvironmentへのアクセスを削除します。
curl -X PUT 'https://www.workato.com/api/members/34567' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"env_roles": [
{
"environment_type": "prod",
"name": "Operator",
"role_type": "privilege_group"
},
{
"environment_type": "dev",
"name": "Admin",
"role_type": "privilege_group"
},
{
"environment_type": "test",
"name": "NoAccess",
"role_type": "privilege_group"
}
]
}'レスポンス2: すべてのEnvironmentでコラボレーターロールを更新する
{
"data": {
"result": "ok"
}
}リクエスト3: 存在しない、または利用できないロールを使用してコラボレーターロールを更新する
コラボレーターのロールを存在しない、または利用できないロールに更新すると、このエンドポイントは400エラーを返します: Role Custom Role not found。
curl -X PUT 'https://www.workato.com/api/members/34567' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"env_roles": [
{
"environment_type": "prod",
"name": "Custom Role",
"role_type": "privilege_group"
}
]
}'レスポンス3: 存在しない、または利用できないロールを使用してコラボレーターロールを更新する
{
"errors": [
{
"code": 400,
"title": "Role Custom Role not found"
}
]
}リクエスト4: 存在しないEnvironmentでコラボレーターロールを更新する
存在しないEnvironmentでコラボレーターのロールを更新すると、このエンドポイントは400エラーを返します: Environment Custom Environment not found。
curl -X PUT 'https://www.workato.com/api/members/34567' \
-H 'Authorization: Bearer <api_token>' \
-H 'Content-Type: application/json' \
-d '{
"env_roles": [
{
"environment_type": "Custom Environment",
"name": "Admin",
"role_type": "privilege_group"
}
]
}'レスポンス4: 存在しないEnvironmentでコラボレーターロールを更新する
{
"errors": [
{
"code": 400,
"title": "Environment Custom Environment not found"
}
]
}コラボレーターを削除する
コラボレーターをIDで削除します。
DELETE /api/members/:idパスパラメーター
| 名前 | タイプ | 説明 |
|---|---|---|
| id | string 必須 | 削除するコラボレーターのID。 |
サンプルリクエスト
curl -X DELETE 'https://www.workato.com/api/members/34567' \
-H 'Authorization: Bearer <api_token>'レスポンス
リクエストが成功すると、204 No Contentステータスコードが返されます。 コラボレーターは削除され、レスポンス本文は空です。
コラボレーターのプロジェクト付与を一覧表示する
ワークスペースのすべてのプロジェクト付与を取得します。 これには、コラボレーターグループを通じて付与されたプロジェクトアクセスは含まれません。
プロジェクト付与
プロジェクト付与は、コラボレーターまたはグループにプロジェクトロールを割り当てます。 Developer APIを使用してプロジェクト付与を管理するにはプロジェクト付与を、UIでプロジェクトロールを管理するにはプロジェクトアクセスとロールを管理するを参照してください。
GET /api/members/:id/project_grantsパスパラメーター
| 名前 | タイプ | 説明 |
|---|---|---|
| id | string 必須 | プロジェクト付与を取得するコラボレーターのID。 |
クエリパラメーター
| 名前 | タイプ | 説明 |
|---|---|---|
| page[number] | integer optional | 取得するページ番号。 デフォルト値は1です。 |
| page[size] | integer optional | 取得するページあたりの項目数。 デフォルト値および最大値は100です。 |
サンプルリクエスト
curl -X GET 'https://www.workato.com/api/members/34567/project_grants?page[number]=1&page[size]=100' \
-H 'Authorization: Bearer <api_token>'レスポンス
{
"data": [
{
"id": "pg-AQAEnmMX-b4rPeT",
"project": {
"id": 178230,
"name": "Development",
"environment": {
"id": 148425,
"type": "dev"
},
},
"project_role": {
"id": "pr-AQAEnmK3-EQpeYM",
"name": "Developers"
}
},
{
"id": "pg-AQAEnmKE-xpCFwT",
"project": {
"id": 178230,
"name": "Sales",
"environment": {
"id": 148426,
"type": "prod"
},
},
"project_role": {
"id": "pr-AQAEnmK3-EQpeYM",
"name": "Developers"
}
}
],
"total": 2,
"page": {
"number": 1,
"size": 100
}
}コラボレーターの権限を取得する
コラボレーターの権限とロールをIDで取得します。 レスポンスは、各Environment(例: dev、test、prod)のロールの配列を次の情報とともに返します:
- Environmentタイプ
- ユーザーロール
- ロールに割り当てられたすべての権限
- ロールタイプ
レスポンスには、従来のモデル(role_type: privilege_group)と新しいモデル(role_type: environment)の両方のロールが含まれます。
GET /api/members/:id/privilegesパスパラメーター
| 名前 | タイプ | 説明 |
|---|---|---|
| id | string 必須 | 権限を取得する予定のコラボレーターのID。 |
サンプルリクエスト
curl -X GET 'https://www.workato.com/api/members/34567/privileges' \
-H 'Authorization: Bearer <api_token>'レスポンス
{
"data": [
{
"environment_type": "dev",
"name": "Operator",
"role_type": "privilege_group",
"privileges": {
"Recipes": [
"read",
"run",
"read_run_history"
],
"Folders": [
"read"
],
"Projects": [
"read"
],
"Use in recipes": [
"all"
],
"Test automation": [
"read"
]
}
},
{
"environment_type": "test",
"name": "Operator",
"role_type": "privilege_group",
"privileges": {
"Recipes": [
"read",
"run",
"read_run_history"
],
"Folders": [
"read"
],
"Projects": [
"read"
],
"Use in recipes": [
"all"
],
"Test automation": [
"read"
]
}
},
{
"environment_type": "prod",
"name": "Operator",
"role_type": "privilege_group",
"privileges": {
"Recipes": [
"read",
"run",
"read_run_history"
],
"Folders": [
"read"
],
"Projects": [
"read"
],
"Use in recipes": [
"all"
],
"Test automation": [
"read"
]
}
}
]
}コラボレーターのプロジェクト権限を取得する
コラボレーターのプロジェクトレベルのアクセスを取得します。 これには、直接割り当てられたアクセス、またはコラボレーターグループのメンバーシップを通じて割り当てられたアクセスが含まれます。 このエンドポイントを使用して、プロジェクト権限を監査できます。
GET /api/members/:id/projects_privilegesパスパラメーター
| 名前 | タイプ | 説明 |
|---|---|---|
| id | string 必須 | プロジェクト権限を取得する予定のコラボレーターのID。 |
サンプルリクエスト
curl -X GET 'https://www.workato.com/api/members/34567/projects_privileges' \
-H 'Authorization: Bearer <api_token>'レスポンス
{
"data": [
{
"environment": {
"id": 123456,
"type": "dev"
},
"projects": {
"61722": {
"Folders": ["create", "view"]
}
}
},
{
"environment": {
"id": 789123,
"type": "prod"
},
"projects": {
"74137": {
"Folders": ["view"]
}
}
}
]
}Last updated: