構成ページを作成する

[アーティクル]
05/25/2022

構成ページは、特別な種類のコンテンツページです。ユーザーは、構成ページを使用して Microsoft Teams アプリのいくつかの側面を構成し、その構成を次の一部として使用します。

[チャネルまたはグループチャット] タブ: ユーザーから情報を収集し、表示するコンテンツページの contentUrl を設定します。
メッセージ拡張機能。
Office 365 コネクタ。

注意

このトピックでは、Microsoft Teams JavaScript クライアント SDK のバージョン 2.0.0 を反映しています。以前のバージョンを使用している場合は、v1 と v2 の違いに関するガイダンスについては、Teams JS SDK の概要を参照してください。

チャネルまたはグループチャットタブを構成する

アプリケーションは、 Microsoft Teams JavaScript クライアントSDK を参照し、app.initialize() を呼び出す必要があります。使用される URL は、セキュリティで保護された HTTPS エンドポイントであり、クラウドから使用できる必要があります。

例

構成ページの例を次の図に示します。

次のコードは、構成ページに対応するコードの例です。

TeamsJS v2
TeamsJS v1

<head>
    <script src='https://statics.teams.cdn.office.net/sdk/v2.0.0/js/MicrosoftTeams.min.js'></script>
</head>
<body>
    <button onclick="(document.getElementById('icon').src = '/images/iconGray.png'); colorClickGray()">Select Gray</button>
    <img id="icon" src="/images/teamsIcon.png" alt="icon" style="width:100px" />
    <button onclick="(document.getElementById('icon').src = '/images/iconRed.png'); colorClickRed()">Select Red</button>

    <script>
        app.initialize();
        let saveGray = () => {
            pages.config.registerOnSaveHandler((saveEvent) => {
                const configPromise = pages.config.setConfig({
                    websiteUrl: "https://yourWebsite.com",
                    contentUrl: "https://yourWebsite.com/gray",
                    entityId: "grayIconTab",
                    suggestedDisplayName: "MyNewTab"
                });
                configPromise.
                    then((result) => {saveEvent.notifySuccess()}).
                    catch((error) => {saveEvent.notifyFailure("failure message")});
            });
        }

        let saveRed = () => {
            pages.config.registerOnSaveHandler((saveEvent) => {
                const configPromise = pages.config.setConfig({
                    websiteUrl: "https://yourWebsite.com",
                    contentUrl: "https://yourWebsite.com/red",
                    entityId: "redIconTab",
                    suggestedDisplayName: "MyNewTab"
                });
                configPromise.
                    then((result) => {saveEvent.notifySuccess();}).
                    catch((error) => {saveEvent.notifyFailure("failure message")});
            });
        }

        let gr = document.getElementById("gray").style;
        let rd = document.getElementById("red").style;

        const colorClickGray = () => {
            gr.display = "block";
            rd.display = "none";
            pages.config.setValidityState(true);
            saveGray()
        }

        const colorClickRed = () => {
            rd.display = "block";
            gr.display = "none";
            pages.config.setValidityState(true);
            saveRed();
        }
    </script>
    ...
</body>

<head>
    <script src='https://statics.teams.cdn.office.net/sdk/v1.6.0/js/MicrosoftTeams.min.js'></script>
</head>
<body>
    <button onclick="(document.getElementById('icon').src = '/images/iconGray.png'); colorClickGray()">Select Gray</button>
    <img id="icon" src="/images/teamsIcon.png" alt="icon" style="width:100px" />
    <button onclick="(document.getElementById('icon').src = '/images/iconRed.png'); colorClickRed()">Select Red</button>

    <script>
        microsoftTeams.initialize();
        let saveGray = () => {
            microsoftTeams.settings.registerOnSaveHandler((saveEvent) => {
                microsoftTeams.settings.setSettings({
                    websiteUrl: "https://yourWebsite.com",
                    contentUrl: "https://yourWebsite.com/gray",
                    entityId: "grayIconTab",
                    suggestedDisplayName: "MyNewTab"
                });
                saveEvent.notifySuccess();
            });
        }
        let saveRed = () => {
            microsoftTeams.settings.registerOnSaveHandler((saveEvent) => {
                microsoftTeams.settings.setSettings({
                    websiteUrl: "https://yourWebsite.com",
                    contentUrl: "https://yourWebsite.com/red",
                    entityId: "redIconTab",
                    suggestedDisplayName: "MyNewTab"
                });
                saveEvent.notifySuccess();
            });
        }

        let gr = document.getElementById("gray").style;
        let rd = document.getElementById("red").style;

        const colorClickGray = () => {
            gr.display = "block";
            rd.display = "none";
            microsoftTeams.settings.setValidityState(true);
            saveGray()
        }

        const colorClickRed = () => {
            rd.display = "block";
            gr.display = "none";
            microsoftTeams.settings.setValidityState(true);
            saveRed();
        }
    </script>
    ...
</body>

タブのコンテンツを灰色または赤色のアイコンで表示するには、構成ページで [灰色を選択] または [赤色を選択] ボタンを選択します。

次の図は、[灰色] のアイコンが選択されたタブコンテンツを表示します。

次の図は、[赤] のアイコンが選択されたタブコンテンツを表示します。

適切なボタンを選択すると、saveGray() または saveRed() のいずれかがトリガーされ、以下が呼び出されます。

pages.config.setValidityState(true) を true に設定します。
pages.config.registerOnSaveHandler()イベントハンドラーがトリガーされます。
アプリの構成ページで [保存] が有効になっています。

構成ページコードは、構成要件が満たされ、インストールを続行できることを Teams に通知します。ユーザーが [保存] を選択すると、Config インターフェースで定義されているように pages.config.setConfig() のパラメーターが設定されます。詳細については、「構成インターフェイス」を参照してください。 saveEvent.notifySuccess() は、コンテンツ URL が正常に解決されたことを示すために呼び出されます。

注意

タイムアウトまでに保存操作 (registerOnSaveHandler へのコールバック) を完了するまでに 30 秒かかります。タイムアウト後、一般的なエラーメッセージが表示されます。
registerOnSaveHandler() を使用して保存ハンドラーを登録する場合、コールバックは saveEvent.notifySuccess() または saveEvent.notifyFailure() を呼び出して、構成の結果を示す必要があります。
保存ハンドラーを登録しない場合、ユーザーが [保存] を選択すると、saveEvent.notifySuccess() 呼び出しが自動的に行われます。

タブのコンテキストを取得する

お使いのタブでは、関連するコンテンツを表示するためにコンテキスト情報が必要になる場合があります。コンテキスト情報は、よりカスタマイズされたユーザーエクスペリエンスを提供することで、タブの魅力をさらに高めます。

タブ構成に使用されるプロパティの詳細については、コンテキストインターフェイスを参照してください。コンテキストデータ変数の値を次の 2 つの方法で収集します。

マニフェストの configurationURL に URL クエリ文字列プレースホルダーを挿入します。
Teams SDK app.getContext() メソッドを使用します。

`configurationUrl` にプレースホルダーを挿入します。

ベース configurationUrl にコンテキストインターフェイスプレースホルダーを追加します。次に例を示します。

ベース URL

...
"configurationUrl": "https://yourWebsite/config",
...

クエリ文字列を含むベース URL

...
"configurationUrl": "https://yourWebsite/config?team={teamId}&channel={channelId}&{locale}"
...

ページのアップロード後、Teams クエリ文字列プレースホルダーが関連する値で更新されます。これらの値を取得して使用するには、構成ページにロジックを含めます。 URL クエリ文字列の操作の詳細については、MDN Web Docs の URLSearchParams を参照してください。次のコード例は、configurationUrl プロパティから値を抽出する方法を示しています。

TeamsJS v2
TeamsJS v1

<script>
   app.initialize();
   const getId = () => {
        let urlParams = new URLSearchParams(document.location.search.substring(1));
        let blueTeamId = urlParams.get('team');
        return blueTeamId
    }
//For testing, you can invoke the following to view the pertinent value:
document.write(getId());
</script>

<script>
   microsoftTeams.initialize();
   const getId = () => {
        let urlParams = new URLSearchParams(document.location.search.substring(1));
        let blueTeamId = urlParams.get('team');
        return blueTeamId
    }
//For testing, you can invoke the following to view the pertinent value:
document.write(getId());
</script>

関数を `getContext()` 使用してコンテキストを取得する

この関数は app.getContext() 、コンテキストインターフェイスオブジェクトを使用して解決する Promise を返します。

次のコードは、この関数を構成ページに追加してコンテキスト値を取得する例を示しています。

TeamsJS v2
TeamsJS v1

<!-- `userPrincipalName` will render in the span with the id "user". -->

<span id="user"></span>
...
<script>
    const contextPromise = app.getContext();
    contextPromise.
        then((context) => {
            let userId = document.getElementById('user');
            userId.innerHTML = context.user.userPrincipalName;
        }).
        catch((error) => {/*Unsuccessful operation*/});
</script>
...

<!-- `userPrincipalName` will render in the span with the id "user". -->

<span id="user"></span>
...
<script>
    microsoftTeams.getContext((context) =>{
        let userId = document.getElementById('user');
        userId.innerHTML = context.userPrincipalName;
    });
</script>
...

コンテキストと認証

ユーザーにアプリの構成を許可する前に認証します。そうしないと、コンテンツに認証プロトコルを持つソースが含まれる可能性があります。詳細については、「Microsoft Teams タブでユーザーを認証する」を参照してください。コンテキスト情報を使用して、認証要求と承認ページ URL を作成します。タブページで使用されているすべてのドメインが manifest.json および validDomains 配列にリストされていることを確認してください。

タブを変更または削除する

マニフェストの canUpdateConfiguration プロパティ trueを . これにより、ユーザーはチャネルまたはグループタブを変更、再構成、または名前変更できます。タブが削除されたときのコンテンツへの影響についてユーザーに通知します。これを行うには、アプリに [削除オプション] ページを含め、(以前の) 構成でプロパティのsetConfig()値removeUrlをsetSettings()設定します。ユーザーは個人用タブをアンインストールできますが、変更することはできません。詳細については、「タブの削除ページを作成する」を参照してください。

setConfig() 削除ページのMicrosoft Teams (以前setSettings()の) 構成:

TeamsJS v2
TeamsJS v1

const configPromise = pages.config.setConfig({
    contentUrl: "add content page URL here",
    entityId: "add a unique identifier here",
    suggestedDisplayName: "add name to display on tab here",
    websiteUrl: "add website URL here //Required field for configurable tabs on Mobile Clients",
    removeUrl: "add removal page URL here"
});
configPromise.
    then((result) => {/*Successful operation*/).
    catch((error) => {/*Unsuccessful operation*/});

microsoftTeams.settings.setSettings({
    contentUrl: "add content page URL here",
    entityId: "add a unique identifier here",
    suggestedDisplayName: "add name to display on tab here",
    websiteUrl: "add website URL here //Required field for configurable tabs on Mobile Clients",
    removeUrl: "add removal page URL here"
});

モバイルクライアント

Teams モバイルクライアントに、チャネルまたはグループタブを表示するように選択した場合は、setConfig()の構成にはwebsiteUrlの値を設定する必要があります。詳細については、「モバイル上のタブに関するガイダンス」を参照してください。

次のステップ

タブのコンテンツページを作成する

構成ページを作成する

このページはお役に立ちましたか?

チャネルまたはグループチャット タブを構成する

例