ユーザー管理

概要

このチュートリアルでは、Frame.io API を介したユーザーの基本的な管理について扱います。ここでは、読者が OAuth2.0 を介した、または開発者トークンでの認証を既に設定していると想定しています。

主要な概念

チームメンバーの様々な役割および権限の具体的で微妙な違いはさておき、Frame.io API を介してユーザーを管理する場合に理解すべき重要な 2 つの鍵があります。

1. チームメンバーは、チームに属しており、チーム内のすべての非プライベートプロジェクトにアクセスできます。チームマネージャーおよび管理者は、いずれもチームメンバーの役割を拡張したものです。
2. プロジェクト共同作業者は、1 個のプロジェクトに属しています。プロジェクトの設定方法によっては、プレゼンテーションの作成、アセットのダウンロード、他の共同作業者の招待を行うことができる場合もあれば、できない場合もあります。

詳しくは、チームメンバーと共同作業者、アカウント管理の役割に関する、アドビのサポートドキュメントを参照してください。

ユーザーがアカウントに参加する方法

一般に、新規ユーザーは、現在のユーザーによって直接、招待されるか、固有のプロジェクト参加 URL を介して招待されます。チームメンバーは、次もできます。

1. 自身をアカウントの公開チーム内の非プライベートプロジェクトに追加
2. 自身をアカウント内の公開チームに追加
3. アカウント内のプライベートチームへの参加をリクエスト

いずれの場合も、参加アクティビティには、一連の論理ステップが示されます。これには、事前テナントの確認、「保留中」のレコードの作成、必要に応じた招待メールまたは参加リクエストメールの送出が含まれます。

幸いなことに、このロジックはすべて、Frame.io API によって抽象化されています。誰かをプロジェクトに追加する場合は、共同作業者ルートを使用します。誰かをチームに招待する場合は、チームメンバールートを使用します。

必要なスコープ

チームメンバーの管理

チームメンバーの追加

新しいチームメンバーをチームに追加するには、次が必要になります。

1. ターゲットチームの id
2. ターゲットユーザーのメールアドレス

そこから、次のような本文ペイロードで、https://api.frame.io/v2/teams/:id/members へのターゲットユーザーのメールで認証された POST を行うだけです。

1
{
2
    "email": "user@example.com"
3
}

招待したユーザーが既に組織のチームメンバーである場合、API 応答は、そのことを表示します。

1
{
2
    "_type": "team_member",
3
    "id": "<team-member-record-id>",
4
    "role": "member",
5
    "team_id": "<team-id>",
6
    "user_id": "<user-id>"
7
}

招待したユーザーがまだ組織に存在しない場合、リクエストにより、招待フローがトリガーされ、API 応答は、次のようになります。

1
{
2
    "_type": "pending_team_member",
3
    "email": "user@example.com",
4
    "id": "<oending-team-member-record-id>",
5
    "role": "member",
6
    "team_id": "<team-id>
7
}

メモ：ユーザーはまだ作成または認識されていないので、pending_team_member 応答にはマッピング可能な user_id はありません。

チームメンバーの削除

チームからチームメンバーを削除するには、次が必要になります。

1. ターゲットチームの id
2. ターゲットユーザーのメールアドレス

ここから、チームメンバーを追加するときと同じ URL への DELETE 呼び出しを行い、それに特別なクエリ文字列を渡します。

DELETE https://api.frame.io/v2/teams/:id/members/_?email=user@example.com

呼び出しが成功すると、API がチームメンバー追加と同様のペイロードを返します。チームメンバーが初めて削除される場合は、呼び出しの時刻に一致する updated_at 属性が表示されます。チームメンバーが以前に削除されている場合、そのタイムスタンプは更新されません（つまり、チームメンバーが最初に削除された時刻が反映されます）。

1
{
2
    "_type": "team_member",
3
    "id": "<team-member-record-id>",
4
    "role": "member",
5
    "team_id": "<team-id>",
6
    "user_id": "<user-id>",
7
    "updated_at": "<timestamp>"
8
}

存在しない、またはチームに関連付けられたことがないチームメンバーを削除しようとすると、404 エラーになります。

プロジェクト共同作業者の管理

プロジェクト共同作業者の追加

共同作業者管理は、チームメンバー管理と非常に似ています。新しい共同作業者をチームに追加するには、次が必要になります。

1. ターゲットプロジェクトの id
2. ターゲットユーザーのメールアドレス

次のような本文ペイロードで、https://api.frame.io/v2/projects/:id/collaborators へのターゲットユーザーのメールで認証された POST を行うだけです。

1
{
2
    "email": "user@example.com"
3
}

招待したユーザーが認識され、共同作業者の役割をすぐにインスタンス化できる場合、API 応答は、そのことを表示し、完全なユーザーオブジェクトを返送します。

1
{
2
    "_type": "collaborator",
3
    "creator_id": "<inviting-user-id>",
4
    "id": "<collaborator-record-id>",
5
    "project_id": "<project-id>",
6
    "user": {
7
        "_type": "user",
8
       <...>
9
    },
10
    "user_id": "<user-id>"
11
}

招待したユーザーが組織にとって新規である場合、リクエストによって招待フローがトリガーされ、API が次のような pending_collaborator レコードで応答します。

1
{
2
    "_type": "pending_collaborator",
3
    "email": "user@example.com",
4
    "id": "<pending-collaborator-record-id>",
5
    "project_id": "<project-id>"
6
}

プロジェクト共同作業者の削除

**メモ：**このプロセスは、チームメンバーが処理される方法（上記）と基本的に同じです。

プロジェクトから共同作業者を削除するには、次が必要になります。

1. ターゲットプロジェクトの id
2. ターゲットユーザーのメールアドレス

ここから、共同作業者を追加するときと同じ URL への DELETE 呼び出しを行い、それに特別なクエリ文字列を渡します。

DELETE https://api.frame.io/v2/projects/:id/collaborators/_?email=user@example.com

呼び出しが成功すると、API がプロジェクト共同作業者追加と同様のペイロードを返します。

1
{
2
    "_type": "collaborator",
3
    "creator_id": "<inviting-user-id>",
4
    "id": "<collaborator-record-id>",
5
    "project_id": "<project-id>",
6
    "user": {
7
        "_type": "user",
8
       <...>
9
    },
10
    "user_id": "<user-id>"
11
}

存在しない、またはプロジェクトに関連付けられたことがない共同作業者を削除しようとすると、404 エラーになります。