Microsoft Graph API を使用して Microsoft Teams で作業するUse the Microsoft Graph API to work with Microsoft Teams

重要

/betaMicrosoft Graph のバージョンの api は変更される可能性があります。APIs under the /beta version in Microsoft Graph are subject to change. 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。Use of these APIs in production applications is not supported.

Microsoft Teams は、Microsoft 365 のチャットベースのワークスペースで、チーム固有の予定表、ファイル、OneNote メモ、Planner プラン、シフトスケジュールなどへの組み込みのアクセスを提供します。Microsoft Teams is a chat-based workspace in Microsoft 365 that provides built-in access to team-specific calendars, files, OneNote notes, Planner plans, Shifts schedules, and more.

Microsoft Teams の主なリソースKey resources in Microsoft Teams

リソースResource メソッドMethods
teamteam 各自のチームの一覧表示すべてのチームの一覧表示作成読み取り更新削除複製アーカイブアーカイブ解除List your teams, list all teams, create, read, update, delete, clone, archive, unarchive
groupgroup メンバーの追加、 メンバーの削除所有者の追加、 所有者の削除ファイルの取得ノートブックの取得プランの取得予定表の取得Add member, remove member, add owner, remove owner, get files, get notebook, get plans, get calendar
channelchannel 一覧表示作成読み取り更新削除List, create, read, update, delete
teamsTabteamsTab 一覧表示作成読み取り更新削除List, create, read, update, delete
teamsAppteamsApp 一覧表示公開更新削除List, publish, update, remove
teamsAppInstallationteamsAppInstallation 一覧表示インストールアップグレード削除List, install, upgrade, remove
chatMessagechatMessage 送信send
callcall 応答拒否リダイレクトミュートミュート解除、画面共有ロールの変更、参加者の一覧表示参加者の招待Answer, reject, redirect, mute, unmute, change screen sharing role, list participants, invite participants
scheduleschedule 作成または置換取得共有Create or replace, get, share
schedulingGroupschedulingGroup 作成一覧表示取得置換削除Create, List, Get, Replace, Delete
shiftshift 作成一覧表示取得置換削除Create, List, Get, Replace, Delete
timeOfftimeOff 作成一覧表示取得置換削除Create, List, Get, Replace, Delete
timeOffReasontimeOffReason 作成一覧表示取得置換削除Create, List, Get, Replace, Delete

Microsoft Teams の制限Microsoft Teams limits

テスト済みの Microsoft Teams のパフォーマンスと容量の制限は、「Microsoft Teams の制限事項と仕様」に記載されています。The tested performance and capacity limits of Microsoft Teams are documented in Limits and specifications for Microsoft Teams. これらの制限は、Microsoft Teams を直接使用している場合でも、Microsoft Graph API を使用している場合でも適用されます。These limits apply whether using Microsoft Teams directly or using Microsoft Graph APIs. すべてのチームには対応するグループがあり、すべてのグループはディレクトリ オブジェクトであるため、グループの数ディレクトリ オブジェクトの数 ("リソース") に制限が発生する可能性もあります。Because every team has a corresponding group, and every group is a directory object, limits on the number of groups and the number of directory objects ("resources") can also come into play.

チャネル内のファイルは SharePoint に保存され、SharePoint Online の制限が適用されます。Files inside channels are stored in SharePoint; SharePoint online limits apply.

詳細については、「throttling limits for Microsoft Teams services (Microsoft Teams サービスの制限の調整)」を参照してください。See also throttling limits for Microsoft Teams services.

チームとグループTeams and groups

Microsoft Graph では、Microsoft Teams は group リソースとして表されます。In Microsoft Graph, Microsoft Teams is represented by a group resource. Microsoft Teams と Microsoft 365 グループの両方が、グループ作業のさまざまなニーズに対応しています。Both Microsoft Teams and Microsoft 365 groups address the various needs of group collaboration. グループ予定表、ファイル、メモ、写真、プランなど、Microsoft Teams と Microsoft 365 グループには、ほとんどすべてのグループベースの機能が適用されています。Almost all the group-based features apply to Microsoft Teams and Microsoft 365 groups, such as group calendar, files, notes, photo, plans, and so on. チームと Microsoft 365 グループの主な違いは、メンバー間の通信モードです。The main difference between a team and a Microsoft 365 group is the mode of communication between members. チーム メンバーのコミュニケーションには、特定のチームのコンテキストで常設チャットが使用されます。Team members communicate by persistent chat in the context of a specific team. Microsoft 365 グループメンバーは、グループの会話で通信します。これは、Outlook のグループのコンテキストで発生する電子メールの会話です。Microsoft 365 group members communicate by group conversations, which are email conversations that occur in the context of a group in Outlook.

チームを持つすべてのグループでは resourceProvisioningOptions プロパティが "Team" に設定されています。Any group that has a team has a resourceProvisioningOptions property that contains "Team".

注: Group.resourceProvisioningOptions プロパティは変更可能です。Note: The Group.resourceProvisioningOptions property can be changed. このコレクションで "Team" を追加または削除しないでください。このようにすると、すべてのチームを一覧表示するときに誤った結果が表示されます。Do not add or remove "Team" from that collection; otherwise, you'll get incorrect results when you list all teams.

チームとグループの API レベルでの違いを以下に示します。The following are the differences at the API level between teams and groups:

注:(たとえば、Microsoft Teams で実行されるタブまたはボットの一部として) スタンドアロン アプリではなく Microsoft Teams アプリのグループ API を使用する場合、記事「Microsoft Teams ページで Microsoft Graph を使用する」のガイダンスに従ってください。Note: If you use the groups API in a Microsoft Teams app rather than in a standalone app - for example as part of a tab or bot running in Microsoft Teams - follow the guidance in the article Using Microsoft Graph in your Microsoft Teams pages.

Microsoft Teams のメンバーシップの変更Membership changes in Microsoft Teams

メンバーと所有者をチームに追加するには、同一 ID の group のメンバーシップを変更します。To add members and owners to a team, change the membership of the group with the same ID.

ユース ケースUse case 動詞Verb URLURL
メンバーを追加するAdd member POSTPOST /groups/{id}/members/$ref/groups/{id}/members/$ref
メンバーを削除するRemove member DELETEDELETE /groups/{id}/members/{userId}/$ref/groups/{id}/members/{userId}/$ref
所有者を追加するAdd owner POSTPOST /groups/{id}/owners/$ref/groups/{id}/owners/$ref
所有者を削除するRemove owner DELETEDELETE /groups/{id}/owners/{userId}/$ref/groups/{id}/owners/{userId}/$ref
チームを更新するUpdate team PATCHPATCH /teams/{id}/teams/{id}

所有者を追加するときには、そのユーザーをメンバーとして追加することをお勧めします。We recommend that when you add an owner, you also add that user as a member. チームの所有者がメンバーではない場合、所有権とメンバーシップの変更は Microsoft Teams にすぐに反映されないことがあります。If a team has an owner who is not also a member, ownership and membership changes might not show up immediately in Microsoft Teams. また、アプリと API によってその処理方法は異なります。In addition, different apps and APIs will handle that differently. たとえば Microsoft Teams ではユーザーがメンバーまたは所有者のいずれであるチームが表示されますが、Microsoft Teams PowerShell コマンドレッドと /me/joinedTeams API ではユーザーがメンバーであるチームだけが表示されます。For example, Microsoft Teams will show teams that the user is either a member or an owner of, while the Microsoft Teams PowerShell cmdlets and the /me/joinedTeams API will only show teams the user is a member of. 混乱を避けるため、すべての所有者をメンバー一覧にも追加してください。To avoid confusion, add all owners to the members list as well.

既知の問題: DELETE /groups/{id}/owners を呼び出すと、/groups/{id}/members 一覧からもユーザーが削除される。Known issue: when DELETE /groups/{id}/owners is called, the user is also removed from the /groups/{id}/members list. この問題を回避するには、所有者とメンバーの両方からユーザーを削除してから 10 秒待ち、その後メンバーにユーザーを再度追加することをお勧めします。To work around this, we recommend that you remove the user from both owners and members, then wait 10 seconds, then add them back to members.

メンバーと所有者を追加または削除するときには、波かっこ { } で ID を囲まないでください。When adding and removing members and owners, don't put braces { } around the ID.

速度Speed 構文Syntax
高速Fast https://graph.microsoft.com/beta/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members/48d31887-5fad-4d73-a9f5-3c356e68a038/$ref
低速Slow https://graph.microsoft.com/beta/groups/{02bd9fd6-8f93-4758-87c3-1fb73740a315}/members/{48d31887-5fad-4d73-a9f5-3c356e68a038}/$ref

同様に、URL またはペイロードの userId が GUID ではなく UPN として表される場合、パフォーマンスが遅くなります。Similarly, if the userId in the URL or payload is expressed as a UPN rather than as a GUID, the performance will be slower.

速度Speed 構文Syntax
高速Fast 48d31887-5fad-4d73-a9f5-3c356e68a03848d31887-5fad-4d73-a9f5-3c356e68a038
低速Slow john@example.comjohn@example.com

低速のパスをとる場合、現在のチーム メンバーまたは所有者が Microsoft Teams アプリケーション/ Web サイトにサインインすると、変更は 1 時間以内に反映されます。When the slower path is taken, if a current team member or owner is signed in to the Microsoft Teams application/website, the change will be reflected within an hour. Microsoft Teams アプリケーション/Web サイトにこれらのユーザーがサインインしていない場合、変更が反映されるのは、いずれかのユーザーがサインインしてから 1 時間後になります。If none of those users are signed in to the Microsoft Teams application/website, the change will not be reflected until an hour after one of them signs in.

注意

テナントのゲストは、常に低速パス経由で処理されます。Tenant guests are always processed via the slow path.

ポーリングの要件Polling requirements

リソースが変更されたかどうかを確認するためにアプリがポーリングを行う場合、実行できるのは 1 日に 1 回だけです。If your app polls to see whether a resource has changed, you can only do that once per day. (teamsAsyncOperation は、頻繁にポーリングされることを意図しているという点で例外です。) それよりも頻繁に変更について知る必要がある場合は、そのリソースのサブスクリプションを作成し、変更通知 (Webhooks) を受け取る必要があります。(teamsAsyncOperation is an exception in that it's intended to be polled frequently.) If you need to hear about changes more frequently than that, you should create a subscription to that resource and receive change notifications (webhooks). 必要なサブスクリプションの種類が見つからない場合は、UserVoice を通じてフィードバックを提供することをお勧めします。If you don't find support for the type of subscription you need, we encourage you to provide feedback via UserVoice.

新しいメッセージをポーリングする場合、サポートされている場合は日付の範囲を指定する必要があります。When polling for new messages, you must specify a date range where supported. 詳細については、「チャネル メッセージの差分を取得する」を参照してください。For details, see get channel messages delta.

ポーリングとは、リソースが変更されたかどうかを確認するために、リソースに対して何度も GET 操作を行うことをさします。Polling is doing a GET operation on a resource over and over again to see if that resource has changed. それがポーリングではない限り、同じリソースに対して 1 日に複数回 GET 操作を行うことができます。You're allowed to GET the same resource multiple times a day, as long as it's not polling. たとえば、ユーザーがお客さまの Web ページを訪問/更新するたびに /me/joinedTeams を GET しても問題はありませんが、その Web ページを更新するために 30 秒ごとにループで /me/joinedTeams を GET することはできません。For example, it is okay to GET /me/joinedTeams every time the user visits/refreshes your web page, but it is not okay to GET /me/joinedTeams in a loop every 30 seconds to refresh that web page.

これらのポーリング要件に従わないアプリは、Microsoft API の使用条件に違反していると見なされます。Apps that don't follow these polling requirements will be considered in violation of the Microsoft APIs Terms of Use. これにより、追加の調整が発生したり、Microsoft API の使用が停止または終了したりする可能性があります。This may result in additional throttling or the suspension or termination of your use of the Microsoft APIs.

新機能What's new

この API セットの最新の新機能と更新プログラムについて説明します。Find out about the latest new features and updates for this API set.

関連項目See also