Microsoft 365 グループのコネクタを作成する

[アーティクル]
04/16/2023

Microsoft Teams アプリを使用すると、Microsoft 365 グループ用の既存のコネクタを追加したり、Teams 内に新しいコネクタを構築したりできます。詳細については、「独自のコネクタを構築する」を参照してください。

Microsoft 365 グループ用のコネクタを作成する方法については、次のビデオを参照してください。

注:

このトピックでは、Microsoft Teams JavaScript クライアントライブラリ (TeamsJS) のバージョン 2.0.x を反映しています。以前のバージョンを使用している場合は、最新の TeamsJS と以前のバージョンの違いに関するガイダンスについては、TeamsJS ライブラリの概要を参照してください。

Teams アプリにコネクタを追加する

パッケージを作成し、AppSource への提出の一部としてコネクタを公開できます。登録済みのコネクタを Teams アプリパッケージの一部として配布できます。 Teams アプリのエントリポイントに関する情報は、機能を参照してください。 Teams 内でアップロードするために、パッケージをユーザーに直接提供することもできます。

コネクタを配布するには、コネクタ開発者ダッシュボードにコネクタを登録します。

Teams でのみ機能するコネクタの場合は、Microsoft Teams ストアにアプリを発行する記事でコネクタを送信する手順に従います。それ以外の場合、登録されたコネクタは、Outlook や Teams など、アプリケーションをサポートするすべての Microsoft 365 製品で機能します。

重要

コネクタは、コネクタ開発者ダッシュボードで [保存] を選択した後で登録されます。 AppSource でコネクタを発行する場合は、Microsoft Teams アプリを AppSource に公開するの手順に従います。 AppSource でアプリを公開しない場合は、それを組織に直接配布します。組織のコネクタを公開した後、コネクタダッシュボードでそれ以上のアクションは必要ありません。

構成エクスペリエンスを統合する

ユーザーは、Teams クライアントから離れることなく、すべてのコネクタ構成エクスペリエンスを完了できます。エクスペリエンスを得るために、Teams は iframe 内に直接構成ページを埋め込むことができます。操作のシーケンスは以下のとおりです。

ユーザーが構成プロセスを開始するために、コネクタを選択します。
ユーザーは Web エクスペリエンスと対話し、構成を完了します。
ユーザーは、コードのコールバックをトリガーする [保存] を選択します。
注:
- このコードでは、Webhook 設定を取得して保存イベントを処理することができます。コードには、後でイベントを投稿するための Webhook が格納されます。
- 構成エクスペリエンスは、Teams 内にインラインで読み込まれます。

既存の Web 構成エクスペリエンスを再利用することも、Teams 専用にホストされた別のバージョンを作成することもできます。コードには TeamsJS ライブラリを含める必要があります。これにより、コードから API にアクセスして、現在のユーザー、チャネル、チームコンテキストの取得、認証フローの開始などの一般的な操作を実行できます。

構成エクスペリエンスを統合するには、以下の操作を行います。

注:

TeamsJS ライブラリ v.2.0.0 以降では、 settings 名前空間の API は、サブ名前空間の API など、 pages.getConfig() ページ名前空間内の同等の API を pages.config 優先して非推奨になりました。詳細については、「 TeamsJS バージョン 2.x.x の新機能」を参照してください。

を呼び出 app.initialize()して TeamsJS を初期化します。
pages.config.setValidityState(true) を呼び出して [保存] を有効にします。

注:

ユーザーの選択またはフィールドの更新に対する応答として microsoftTeams.pages.config.setValidityState(true) を呼び出す必要があります。
ユーザーが [保存] を選択したときに呼び出されるイベントハンドラーを登録microsoftTeams.pages.config.registerOnSaveHandler()します。
microsoftTeams.pages.config.setConfig() を呼び出し、コネクタ設定を保存します。保存された設定は、ユーザーがコネクタの既存の構成を更新しようとした場合にも、構成ダイアログに表示されます。
microsoftTeams.pages.getConfig() を呼び出し、URL を含む Webhook プロパティを取得します。

注:

再設定する場合は、ページが最初にロードされたときに microsoftTeams.pages.getConfig() を呼び出す必要があります。
ユーザーがコネクタを削除した場合に呼び出される microsoftTeams.pages.config.registerOnRemoveHandler() イベントハンドラーを登録します。

このイベントにより、サービスはクリーンアップアクションを実行できます。

以下のコードは、カスタマーサービスやサポートなしでコネクタ設定ページを作成するためのサンプル HTML です。

<h2>Send notifications when tasks are:</h2>
<div class="col-md-8">
    <section id="configSection">
        <form id="configForm">
            <input type="radio" name="notificationType" value="Create" onclick="onClick()"> Created
            <br>
            <br>
            <input type="radio" name="notificationType" value="Update" onclick="onClick()"> Updated
        </form>
    </section>
</div>

<script src="https://res.cdn.office.net/teams-js/2.2.0/js/MicrosoftTeams.min.js" integrity="sha384-Q2Z9S56exI6Oz/ThvYaV0SUn8j4HwS8BveGPmuwLXe4CvCUEGlL80qSzHMnvGqee" crossorigin="anonymous"></script>
<script src="/Scripts/jquery-1.10.2.js"></script>

<script>
        function onClick() {
            pages.config.setValidityState(true);
        }

        await microsoftTeams.app.initialize();
        pages.config.registerOnSaveHandler(function (saveEvent) {
            var radios = document.getElementsByName('notificationType');

            var eventType = '';
            if (radios[0].checked) {
                eventType = radios[0].value;
            } else {
                eventType = radios[1].value;
            }

            await pages.config.setConfig({
                entityId: eventType,
                contentUrl: "https://YourSite/Connector/Setup",
                removeUrl:"https://YourSite/Connector/Setup",
                configName: eventType
                });

            pages.getConfig().then(async (config) {
                // We get the Webhook URL from config.webhookUrl which needs to be saved. 
                // This can be used later to send notification.
            });

            saveEvent.notifySuccess();
        });

        pages.config.registerOnRemoveHandler(function (removeEvent) {
            alert("Removed" + JSON.stringify(removeEvent));
        });

</script>

ページの読み込みの一部としてユーザーを認証するには、タブの認証フローを参照して、ページが埋め込まれたときにサインインを統合してください。

注:

TeamsJS v.2.0.0 より前のコードでは、クライアント間の互換性上の理由から、呼び出す microsoftTeams.authentication.registerAuthenticationHandlers() 前に URL と成功または失敗のコールバックメソッドを使用してを呼び出す authenticate() 必要があります。 TeamsJS v.2.0.0 以降、 registerAuthenticationHandlers は、必要な認証パラメーターを使用して authentication() を直接呼び出すことに優先して非推奨になりました。

`getConfig` 件の応答のプロパティ

注:

呼び出しによって getConfig 返されるパラメーターは、タブからこのメソッドを呼び出すと異なり、リファレンスに記載されているものとは異なります。

getConfig 件の応答のプロパティのパラメーターとその詳細についてはとおりです。

パラメーター	詳細
`entityId`	`setConfig()` を呼び出す場合にコードで設定されたエンティティ ID。
`configName`	`setConfig()` を呼び出す場合にコードで設定される構成名。
`contentUrl`	`setConfig()` を呼び出す場合にコードによって設定される、構成ページの URL。
`webhookUrl`	コネクタ用に作成された Webhook URL。 WEBhook URL を使用して、構造化 JSON を POST してチャネルにカードを送信します。 `webhookUrl`は、アプリケーションがデータを正常に返す場合にのみ返されます。
`appType`	返される値は、`mail`、、`groups`、または `teams` Microsoft 365 Mail、Microsoft 365 グループ、または Teams に対応します。それぞれ。
`userObjectId`	コネクタのセットアップを開始した Microsoft 365 ユーザーに対応する一意の ID。セキュリティで保護する必要があります。この値を使用して、サービスで構成を設定した Microsoft 365 のユーザーを関連付けることができます。

編集の処理

コードは、既存のコネクタ構成を編集するために戻るユーザーを処理する必要があります。これを行うには、初期構成時に以下のパラメーターを指定して microsoftTeams.pages.config.setConfig() を呼び出します。

entityId は、ユーザーがサービスによって構成および理解されたことを表すカスタム ID です。
configName は、構成コードで取得できる名前です。
contentUrl は、ユーザーが既存のコネクタ構成を編集したときに読み込まれるカスタム URL です。

この呼び出しは、保存イベントハンドラーの一部として行われます。次に contentUrl 、が読み込まれたら、を呼び出 getConfig() して、構成ユーザーインターフェイス内の設定またはフォームを事前に設定する必要があります。

削除の処理

ユーザーが既存のコネクタ構成を削除したときに、イベントハンドラーを実行できます。このハンドラーは、microsoftTeams.pages.config.registerOnRemoveHandler() メソッドを実装することで登録します。このハンドラーは、データベースからエントリを削除するなどのクリーンアップ操作を実行するために使用されます。

アプリマニフェストにコネクタを含める

開発者ポータル (https://dev.teams.microsoft.com) から自動生成されたアプリマニフェスト (以前は Teams アプリマニフェスト) をダウンロードします。アプリをテストまたは発行する前に、次の手順を実行します。

アイコンを 2 つ含めます。
iconsアプリマニフェストファイルの部分を変更して、URL ではなくアイコンのファイル名を含めます。

次の manifest.json の 例には、アプリのテストと送信に必要な要素が含まれています。

注:

次の例の id と connectorId を、コネクタの GUID に置き換えます。

コネクタを使用した manifest.json の例

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "id": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
  "version": "1.0",
  "developer": {
    "name": "Publisher",
    "websiteUrl": "https://www.microsoft.com",
    "privacyUrl": "https://www.microsoft.com",
    "termsOfUseUrl": "https://www.microsoft.com"
  },
  "description": {
    "full": "This is a small sample app we made for you! This app has samples of all capabilities Microsoft Teams supports.",
    "short": "This is a small sample app we made for you!"
  },
  "icons": {
    "outline": "sampleapp-outline.png",
    "color": "sampleapp-color.png"
  },
  "connectors": [
    {
      "connectorId": "e9343a03-0a5e-4c1f-95a8-263a565505a5",
      "scopes": [
        "team"
      ]
    }
  ],
  "name": {
    "short": "Sample App",
    "full": "Sample App"
  },
  "accentColor": "#FFFFFF",
  "needsIdentity": "true"
}

コネクタをテストする

コネクタをテストするには、他のアプリと同じ方法でコネクタをチームにアップロードします。 2 つのアイコンファイルとコネクタ開発者ダッシュボードから、アプリマニフェストファイルを使用して .zip パッケージを作成できます。これは、「アプリマニフェストにコネクタを含める」の指示にしたがって変更されます。

アプリをアップロードしたら、任意のチャネルからコネクタリストを開きます。一番下までスクロールして、アプリが [アップロード済み] セクションに表示されていることを確認します。

[コネクタ] ダイアログボックスの [アップロード] セクションのスクリーンショット。

注:

フローは、ホストされたエクスペリエンスとして Teams 内で完全に発生します。

HttpPOST アクションが正しく動作していることを確認するために、お使いのコネクタにメッセージを送信します。

詳細なガイドに従って、Teams でコネクタを作成してテストします。

Webhook とコネクタを配布する

チーム用の受信 Webhook を直接作成します。
構成ページを追加し、受信 Webhook をコネクタに発行してMicrosoft 365 グループします。
AppSource への提出の一部としてコネクタをパッケージ化して公開します。

コードサンプル

次のテーブルに、サンプル名とその説明を示します。

サンプルの名前	説明	.NET	Node.js
コネクタの TODO 通知	このサンプルでは、Teams チャネルの通知を生成して送信するMicrosoft 365 グループ用のコネクタを示します。	表示	表示
汎用コネクタのサンプル	このサンプルでは、Webhook をサポートするすべてのシステム用にカスタマイズしやすい汎用コネクタを示します。	該当なし	表示

ステップバイステップのガイド

ステップバイステップガイドに従って、Teams でコネクタを構築してテストします。

Microsoft 365 グループのコネクタを作成する

Teams アプリにコネクタを追加する

構成エクスペリエンスを統合する

`getConfig` 件の応答のプロパティ

編集の処理

削除の処理

アプリマニフェストにコネクタを含める

コネクタを使用した manifest.json の例

コネクタをテストする

Webhook とコネクタを配布する

コードサンプル

ステップバイステップのガイド

関連項目

フィードバック

その他のリソース

Microsoft 365 グループのコネクタを作成する

Teams アプリにコネクタを追加する

構成エクスペリエンスを統合する

getConfig 件の応答のプロパティ

編集の処理

削除の処理

アプリ マニフェストにコネクタを含める

コネクタを使用した manifest.json の例

コネクタをテストする

Webhook とコネクタを配布する

コード サンプル

ステップ バイ ステップのガイド

関連項目

フィードバック

その他のリソース

`getConfig` 件の応答のプロパティ

アプリマニフェストにコネクタを含める

コードサンプル

ステップバイステップのガイド