Microsoft Graph APIを使用すると、アプリはViva Engageでコミュニティとロールを管理できます。 Viva Engageは、organization全体でユーザーを接続して共有および学習するアプリのMicrosoft Viva スイートのためのソーシャル ファブリックです。 これは、従業員がリーダー、同僚、コミュニティとつながり、知識やアイデアを共有し、職場に属している人を見つけることができる場所です。
重要
Microsoft Graph のViva Engage API は、ネイティブ モードのViva Engage ネットワークでのみサポートされます。 この API を使用して、レガシまたは外部のViva Engage ネットワークを管理することはできません。
Authorization
Microsoft Graph で Viva Engage API を呼び出すには、アプリがアクセス トークンを取得する必要があります。 アクセス トークンの詳細については、「Microsoft Graph を呼び出すためのトークンの取得」を参照してください。 アプリには、適切なアクセス許可も必要です。 詳細については、「Microsoft Graph のアクセス許可リファレンス」を参照してください。
一般的なユース ケース
次の表に、Viva Engage API の一般的なユース ケースを示します。
| ユース ケース | API | メモ |
|---|---|---|
| コミュニティを作成する | POST /employeeExperience/communities | 成功した場合、このメソッドは engagementAsyncOperation オブジェクトへのリンクを含む202 Accepted応答コードを返します。 |
| コミュニティ作成の状態のポーリング | GET /employeeExperience/engagementAsyncOperations/{engagementAsyncOperationId} | 成功した場合、このメソッドは応答コード 200 OK と応答本文に engagementAsyncOperation オブジェクトを返します。 この場所に GET 要求を行って、操作の状態を定期的にチェックします。チェックの間>30 秒待ちます。 要求が正常に完了すると、 状態 は succeeded を示し、 resourceLocation は 作成または変更されたリソースを指します。 |
| 作成後にコミュニティを取得する | GET /employeeExperience/community/{communityId} | 成功した場合、このメソッドは応答コード 200 OK と、応答本文の コミュニティ オブジェクトを返します。 コミュニティ オブジェクトは、コミュニティ メンバーシップと所有権管理に使用できる関連付けられた Microsoft 365 グループ ID を参照します。 |
| コミュニティの一覧を取得する | GET /employeeExperience/communities | 成功した場合、このメソッドは200 OK応答コードと、応答本文のViva Engageコミュニティ オブジェクトのコレクションを返します。 |
| コミュニティを更新する | PATCH /employeeExperience/community/{communityId} | 成功した場合、このメソッドは既存のViva Engage コミュニティを更新し、204 No Content応答コードを返します。 |
| コミュニティを削除する | DELETE /employeeExperience/community/{communityId} | 成功した場合、このメソッドは、接続されている Microsoft 365 グループ、OneNote ノートブック、Planner プランなど、関連付けられているすべての Microsoft 365 コンテンツと共に、Viva Engage コミュニティを削除します。 詳細については、「Microsoft 365 グループに接続されているViva Engage コミュニティを削除した場合の動作」を参照してください。 |
| コミュニティにメンバーを追加する | POST /groups/{groupId}/members/$ref | 新しいメンバーがグループに追加されると、コミュニティの関連付けられているメンバーシップが自動的に更新されます。 |
| コミュニティからメンバーを削除する | DELETE /groups/{groupId}/members/{userId}/$ref | メンバーがグループから削除されると、コミュニティの関連付けられているメンバーシップが自動的に更新されます。 |
| コミュニティ管理者を追加する | POST /groups/{groupId}/owners/$ref | ユーザーがグループ所有者として追加されると、関連付けられているコミュニティの管理者になります。 |
| コミュニティ管理者を削除する | DELETE /groups/{groupId}/owners/{userId}/$ref | グループ所有者が削除されると、関連付けられているコミュニティの管理者を停止します。 グループの最後の所有者 (ユーザー オブジェクト) を削除することはできません。 |
| ロールを管理する | ||
| Viva Engageでサポートされているロールの種類の静的な一覧を取得する | GET /employeeExperience/roles | 成功した場合、このメソッドは 200 OK 応答コードと応答本文のロールの一覧を返します。 |
| 特定のViva Engage ロールを持つユーザーの一覧を取得する | GET /employeeExperience/roles/{engagementRoleId}/members | 成功した場合、このメソッドは 200 OK 応答コードと応答本文のエンゲージメント ロール メンバーの一覧を返します。 |
| サインインしているユーザーに割り当てられているViva Engageロールの一覧を取得する | GET /me/employeeExperience/assignedRoles | 成功した場合、このメソッドは 200 OK 応答コードと応答本文のロールの一覧を返します。 |
| ユーザーに割り当てられているViva Engageロールの一覧を取得する | GET /users/{userId}/employeeExperience/assignedRoles | 成功した場合、このメソッドは 200 OK 応答コードと応答本文のロールの一覧を返します。 |
| ユーザーにViva Engageロールを割り当てる | POST /employeeExperience/roles/{engagementRoleId}/members | 成功した場合、このメソッドはユーザーにViva Engageロールを割り当てます。 |
| ユーザーからViva Engageロールを削除する | DELETE /employeeExperience/roles/{roleId}/members/{userId} | 成功した場合、このメソッドはユーザーからViva Engageロールを取り消します。 |
コミュニティとグループ
ネイティブ モードViva Engageネットワークの場合、新しいViva Engage コミュニティを作成すると、接続された Microsoft 365 グループが作成され、新しい SharePoint サイト、OneNote ノートブック、Planner プランも作成されます。 関連付けられているグループを使用して、次のようにコミュニティの操作を管理します。
- グループ メンバーを追加または削除する
- グループの所有権を管理する
- グループを削除する
- グループの名前を変更する
- グループの説明を更新する
Viva Engage コミュニティと Microsoft 365 グループの関係の詳細については、「Viva EngageとMicrosoft 365 グループ」を参照してください。
手記：グループの作成 API を使用して、Viva Engage コミュニティをプロビジョニングすることはできません。
ロールを管理する
Viva Engageは、定義済みの管理ロール (ネットワーク管理者や検証済み管理者など) とプラットフォーム内の企業コミュニケーション ロールの割り当てを有効にすることで、ロールベースのアクセスをサポートします。
これらの割り当て可能なロールは、Viva Engageによって事前に定義され、管理されます。 カスタム ロールを作成または削除することはできません。 詳細については、「Viva Engageで管理者ロールを管理する」を参照してください。
Microsoft EntraロールはMicrosoft Entra管理センターを通じて管理されますが、Viva Engage プラットフォームと Microsoft Graph API を使用して、Viva Engage固有のロールを割り当てて管理できます。 詳細については、「Microsoft 365 管理センター ガイド」を参照してください。
API の制限
Viva Engage API 呼び出しはレート制限の対象となり、30 秒の期間内にユーザーごとにアプリごとに 10 件の要求が許可されます。 レート制限を超えると、後続のすべての要求から 429 Too Many Requests 応答コードが返されます。
Microsoft Graph で調整を処理する方法のガイダンスについては、「 Microsoft Graph の調整ガイダンス」を参照してください。
次の手順
- Microsoft Graph APIを使用して、Viva Engageのコミュニティとロールを管理します。
- Graph エクスプローラーでViva Engage API を試してください。