Microsoft Graph を使用してサードパーティのプラットフォーム メッセージを Teams にインポートする

  • [アーティクル]

Microsoft Graph を使用すると、ユーザーの既存のメッセージ履歴とデータを外部システムから Teams チャネルに移行できます。 Teams 内でサード パーティのプラットフォーム メッセージング階層を再現できるようにすることで、ユーザーはシームレスな方法で通信を継続し、中断することなく続行できます。

注:

今後、Microsoft は、インポートされるデータの量に基づいて、お客様またはお客様の顧客に追加料金の支払いを要求する場合があります。

インポートの概要

大まかに言うと、インポート プロセスは次の要素で構成されます。

  1. バックインタイム タイムスタンプを持つチームを作成する。
  2. バックインタイム タイムスタンプを持つチャネルを作成する。
  3. 外部のバックインタイム 日付メッセージをインポートする。
  4. チームとチャネルの移行プロセスを完了す。
  5. チーム メンバーを追加する。

前提条件

メッセージ データを分析して準備する

  • サード パーティのデータを確認して、移行する内容を決定します。
  • 選択したデータをサード パーティのチャット システムから抽出します。
  • サード パーティのチャット構造を Teams 構造にマッピングします。
  • インポート データを移行に必要な形式に変換します。

教育機関向け Microsoft 365 テナントをセットアップする

  • インポート データに Microsoft 365 テナントが存在することを確認します。 Teams 用の Microsoft 365 テナントの設定の詳細については、「 Microsoft 365 テナントを準備する」を参照してください。
  • チーム メンバーが Microsoft Entra ID であることを確認します。 詳細については、「Microsoft Entra ID に新しいユーザーを追加する」を参照してください。

手順 1: リストを作成する

既存のデータを移行するため、元のメッセージ タイムスタンプを維持し、移行プロセス中にメッセージング アクティビティを防止することは、Teams でユーザーの既存のメッセージ フローを再作成する際に重要です。 これは次のように実現されます。

チーム リソース createdDateTime プロパティを使用して、バックインタイム タイムスタンプを持つ新しいチームを作成します。 移行プロセスが完了するまで migration mode のチーム内のほとんどのアクティビティからユーザーを制限する特別な状態の新しいチームを配置します。 teamCreationMode インスタンス属性と migration 値を POST リクエストに含めて、移行用に作成された新しいチームを明示的に識別します。

注:

createdDateTime フィールドは、移行されたチームまたはチャネルのインスタンスにのみ設定されます。

アクセス許可

ScopeName DisplayName 説明 型 管理者の同意はありましたか? 対象となるエンティティ/API
Teamwork.Migrate.All Microsoft Teams への移行の管理 Teams に移行するためのリソースを作成して管理する。 アプリケーション専用 はい POST /teams

POST リクエストの例については、「要求 (移行状態でチームを作成する)」をご覧ください。

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
  "@microsoft.graph.teamCreationMode": "migration",
  "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
  "displayName": "My Sample Team",
  "description": "My Sample Team’s Description",
  "createdDateTime": "2020-03-14T11:22:17.043Z"
}

応答

HTTP/1.1 202 Accepted
Location: /teams/{team-id}/operations/{operation-id}
Content-Location: /teams/{team-id}

エラー メッセージ

400 Bad Request

次のシナリオでは、エラー メッセージを受け取ることができます。

  • createdDateTime が将来に向けて設定されている場合。
  • createdDateTime は正しく指定されていますが、teamCreationMode インスタンス属性が欠落しているか、無効な値に設定されています。

ステップ 2: 移行タスクを作成する

インポートされたメッセージのチャネルの作成は、チームの作成シナリオと似ています。

チャネル リソース createdDateTime プロパティを使用して、バックインタイム タイムスタンプを持つ新しいチャネルを作成します。 新しいチャネルを migration mode に配置します。これは、移行プロセスが完了するまで、チャネル内のほとんどのチャット アクティビティからユーザーを制限する特別な状態です。 channelCreationMode インスタンス属性と migration 値を POST リクエストに含めて、移行用に作成された新しいチームを明示的に識別します。

アクセス許可

ScopeName DisplayName 説明 型 管理者の同意はありましたか? 対象となるエンティティ/API
Teamwork.Migrate.All Microsoft Teams への移行の管理 Teams に移行するためのリソースを作成して管理する。 アプリケーション専用 はい POST /teams

リクエスト (移行状態でチャネルを作成する)

POST https://graph.microsoft.com/v1.0/teams/{team-id}/channels
Content-Type: application/json

{
  "@microsoft.graph.channelCreationMode": "migration",
  "displayName": "Architecture Discussion",
  "description": "This channel is where we debate all future architecture plans",
  "membershipType": "standard",
  "createdDateTime": "2020-03-14T11:22:17.047Z"
}

応答

HTTP/1.1 202 Accepted

{
   "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels/$entity",
   "id":"id-value",
   "createdDateTime":null,
   "displayName":"Architecture Discussion",
   "description":"This channel is where we debate all future architecture plans",
   "isFavoriteByDefault":null,
   "email":null,
   "webUrl":null,
   "membershipType":null,
   "moderationSettings":null
}

エラー メッセージ

400 Bad Request

次のシナリオでは、エラー メッセージを受け取ることができます。

  • createdDateTime が将来に向けて設定されている場合。
  • createdDateTime が正しく指定されているが、channelCreationMode インスタンス属性が欠落しているか、無効な値に設定されている場合。

手順 3: メッセージをインポートする

チームとチャネルが作成されたら、要求本文の と from キーを使用してcreatedDateTime、バックインタイム メッセージの送信を開始できます。

注:

  • メッセージ スレッド createdDateTime より前の createdDateTime でインポートされたメッセージはサポートされていません。
  • createdDateTime は、同じスレッド内のメッセージ間で一意である必要があります。
  • createdDateTime は、ミリ秒単位の精度のタイム スタンプをサポートします。 たとえば、受信要求メッセージの createdDateTime 値が 2020-09-16T05:50:31.0025302Z の場合、メッセージの取り込み時に 2020-09-16T05:50:31.002Z に変換されます。

要求 (テキスト専用の POST メッセージ)

POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages

{
   "createdDateTime":"2019-02-04T19:58:15.511Z",
   "from":{
      "user":{
         "id":"id-value",
         "displayName":"Joh Doe",
         "userIdentityType":"aadUser"
      }
   },
   "body":{
      "contentType":"html",
      "content":"Hello World"
   }
}

応答

HTTP/1.1 200 OK

{
   "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels('channel-id')/messages/$entity",
   "id":"id-value",
   "replyToId":null,
   "etag":"id-value",
   "messageType":"message",
   "createdDateTime":"2019-02-04T19:58:15.58Z",
   "lastModifiedDateTime":null,
   "deleted":false,
   "subject":null,
   "summary":null,
   "importance":"normal",
   "locale":"en-us",
   "policyViolation":null,
   "from":{
      "application":null,
      "device":null,
      "conversation":null,
      "user":{
         "id":"id-value",
         "displayName":"Joh Doe",
         "userIdentityType":"aadUser"
      }
   },
   "body":{
      "contentType":"html",
      "content":"Hello World"
   },
   "attachments":[
   ],
   "mentions":[
   ],
   "reactions":[
   ]
}

エラー メッセージ

400 Bad Request

リクエスト (インライン画像でメッセージを投稿)

注:

  • リクエストは chatMessage の一部であるため、このシナリオには特別な権限スコープはありません。
  • chatMessage のスコープはここに適用されます。
POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/messages

{
  "body": {
        "contentType": "html",
        "content": "<div><div>\n<div><span><img height=\"250\" src=\"../hostedContents/1/$value\" width=\"176.2295081967213\" style=\"vertical-align:bottom; width:176px; height:250px\"></span>\n\n</div>\n\n\n</div>\n</div>"
    },
    "hostedContents":[
        {
            "@microsoft.graph.temporaryId": "1",
            "contentBytes": "iVBORw0KGgoAAAANSUhEUgAAANcAAAExCAYAAADvFzeeAAAXjklEQVR4Ae2d/XNU1RnH+9e0FFrA0RCIyaS8hRA0HV5KbS1gHRgVpjMClY4GHJ3yYm1HCmXaWttaaZUZtIIFKYi8lFAkvOQ9u5vN225IARVBbX9/Os9NbrLZbMjmhCfJPX5+2Lmb3T25y3O+n/M599x7w9f+++UXwoMakIF7n4GvUdR7X1RqSk01A8CFuZm5GGUAuIwKi72wF3ABF+YyygBwGRUWc2Eu4AIuzGWUAeAyKizmwlzABVyYyygDwGVUWMyFuYALuDCXUQaAy6iwmAtzARdwfWXMdeuzT+TGxz3Sfb1LunrapL07IW3pePDQ5/qavqef0c+OdYAELuAac4jGGkLL9rdvfyo9N9ODQAqBGmmrwGlb/R0u3xG4gMspOC5hG882CoRaaCSA8n1ff9doIQMu4PIOrus3u+8ZVNnw6e/Od5AALuDKOyz5hmqiPnfnzi1J9bSbgRWCpvvQfY307wQu4BoxJCOFaDK8rwsQmQsUIQhWW93XSIsewAVckYdLQ24F0Ui/926AARdwRRounZ6Np7GyYdN9DzdFBC7gijRc43GMlQ1U9s/6HXJNjYELuHI<<-----Removed----->>>>",
            "contentType": "image/png"
        }
    ]
}

応答

HTTP/1.1 200 OK

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#teams('team-id')/channels('channel-id')/messages/$entity",
    "id": "id-value",
    "replyToId": null,
    "etag": "id-value",
    "messageType": "message",
    "createdDateTime": "2019-02-04T19:58:15.511Z",
    "lastModifiedDateTime": null,
    "deleted": false,
    "subject": null,
    "summary": null,
    "importance": "normal",
    "locale": "en-us",
    "policyViolation": null,
    "from": {
        "application": null,
        "device": null,
        "conversation": null,
        "user": {
            "id": "id-value",
            "displayName": "Joh Doe",
            "userIdentityType": "aadUser"
        }
    },
      "body": {
        "contentType": "html",
        "content": "<div><div>\n<div><span><img height=\"250\" src=\"https://graph.microsoft.com/teams/teamId/channels/channelId/messages/id-value/hostedContents/hostedContentId/$value\" width=\"176.2295081967213\" style=\"vertical-align:bottom; width:176px; height:250px\"></span>\n\n</div>\n\n\n</div>\n</div>"
    },
    "attachments": [],
    "mentions": [],
    "reactions": []
}

手順 4: 移行モードを完了する

メッセージ移行プロセスが完了すると、チームとチャネルの両方が、 メソッドを使用して completeMigration 移行モードから取り出されます。 この手順では、チーム メンバーが一般的に使用するためにチーム リソースとチャネル リソースを開きます。 アクションは team インスタンスにバインドされます。 チームが完了する前に、すべてのチャネルを移行モードから完了する必要があります。

要求 (エンド チャネル移行モード)

POST https://graph.microsoft.com/v1.0/teams/team-id/channels/channel-id/completeMigration

応答

HTTP/1.1 204 NoContent

要求 (エンド チーム移行モード)

POST https://graph.microsoft.com/v1.0/teams/team-id/completeMigration

応答

HTTP/1.1 204 NoContent

migrationMode にない team または channel で呼び出されたアクション。

手順 5: チーム メンバーを追加する

Teams UI を使用して、または Microsoft Graph [メンバーを追加] API を使用して、チームにメンバーを追加できます。

要求 (メンバーの追加)

POST https://graph.microsoft.com/beta/teams/{team-id}/members
Content-type: application/json
Content-length: 30

{
   "@odata.type": "#microsoft.graph.aadUserConversationMember",
   "roles": [],
   "user@odata.bind": "https://graph.microsoft.com/beta/users/{user-id}"
}

応答

HTTP/1.1 204 No Content

ヒントとその他の情報

  • completeMigration 要求が行われた後、それ以降のメッセージをチームにインポートすることはできません。

  • 新しいチームにチーム メンバーを追加できるのは、completeMigration 要求が成功した応答を返した後だけです。

  • 調整: チャネルあたり 5 つの RPS でメッセージがインポートされます。

  • 移行結果を修正する必要がある場合は、チームを削除し、手順を繰り返してチームとチャネルを作成し、メッセージを再移行する必要があります。

注:

現在、インライン イメージは、インポート メッセージ API スキーマでサポートされている唯一の種類のメディアです。

コンテンツ スコープをインポートする

次の表に、コンテンツ スコープを示します。

スコープ内 現在はスコープ外です
チーム メッセージとチャネル メッセージ 1:1 とグループ チャット メッセージ
元のメッセージの作成時刻 プライベート チャネル
メッセージの一部としてのインライン イメージ ＠メンション
SPO または OneDrive 内の既存のファイルへのリンク リアクション
リッチ テキストを含むメッセージ ビデオ
メッセージ応答チェーン お知らせ
高スループット処理 コード スニペット
ステッカー
絵文字
見積もり
チャネル間のクロス 投稿
共有チャネル

関連項目