Microsoft Graph API を使用して Viva Engage を操作する
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
Microsoft Graph API を使用すると、アプリで Viva Engage のコミュニティを管理できます。 Viva Engage は、組織全体のユーザーを共有および学習するための 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 ネットワークの場合、新しい Viva Engage コミュニティを作成すると、接続された Microsoft 365 グループが作成され、新しい SharePoint サイト、OneNote ノートブック、Planner プランも作成されます。 関連付けられているグループを使用して、次のようにコミュニティの操作を管理します。
- グループ メンバーを追加または削除する
- グループの所有権を管理する
- グループを削除する
- グループの名前を変更する
- グループの説明を更新する
Viva Engage コミュニティと Microsoft 365 グループの関係の詳細については、「 Viva Engage と Microsoft 365 Groups」を参照してください。
手記：グループの作成 API を使用して Viva Engage コミュニティをプロビジョニングすることはできません。
API の制限
Viva Engage API 呼び出しはレート制限の対象となり、30 秒以内にユーザーごとにアプリごとに 10 件の要求が許可されます。 レート制限を超えると、後続のすべての要求から 429 Too Many Requests 応答コードが返されます。
Microsoft Graph で調整を処理する方法のガイダンスについては、「 Microsoft Graph の調整ガイダンス」を参照してください。
次の手順
- Microsoft Graph API を使用して、Viva Engage のコミュニティを管理します。
- Graph エクスプローラーで Viva Engage API を試してください。