Share via

アダプティブ カード テンプレート サービス

  • [アーティクル]

アダプティブ カード テンプレート サービスは、一連の既知のテンプレートをだれでも検索、投稿、共有できるようにする概念実証サービスです。

一部のデータを表示する必要があるものの、そのためにカスタムのアダプティブ カードを作成するのが面倒な場合に便利です。

アダプティブ カード テンプレートの概要については、こちらをお読みください。

重要

使用条件

このアルファレベル サービスは、エラーを含めて現状のまま提供されており、いかなるサポートも提供されません。 本サービスからのデータ収集には、Microsoft プライバシー ステートメントが適用されます。

これらの機能はプレビュー段階であり、変更される可能性があります。 フィードバックは歓迎されるだけでなく、ユーザーが必要とする機能を確実に提供するために不可欠です。

このサービスがどのように役立つか

財務データ、Microsoft Graph データ、schema.org データ、組織内のカスタム データなど、何らかのデータを入手したとします。

そのデータをユーザーに示す必要がある場合、

これまでは、エンドユーザーに配信するすべてのフロントエンド スタックにカスタム UI コードを記述する必要がありました。

では、アプリ自体がデータの種類に基づいて新しい UI テンプレートを "学習" できるとしたらどうでしょうか。 自分のプロジェクト内、組織内、またはインターネット全体で、すべてのユーザーが共通の UI テンプレートを投稿、拡張、共有できる場合です。

カード テンプレート サービスとは

カード テンプレート サービスは、単純な REST エンドポイントで、次のことに役立ちます。

  • データの構造を分析してテンプレートを検索します
  • テンプレートを取得して、クライアントに直接バインドできます。データをサーバーに送信したり、デバイスを離れたりしないで済みます
  • クライアント側でのデータ バインディングが不適切または不可能である場合、サーバー上でテンプレートを設定します

これには次のことが関係しています。

  • GitHub によってサポートされるオープンソースの共有テンプレート リポジトリ。 (リポジトリは現在非公開ですが、いくつかの細かな処理が済み次第公開されます)
  • すべてのテンプレートが、このリポジトリに含まれるフラットな JSON ファイルです。このため、開発者ワークフローの自然な一部として編集、投稿、共有を行なえます。
  • サービスのコードが利用できるようになります。これにより、ユーザーが最も利用しやすい場所でホストできます。

サービスの使用

すべてのテンプレートを取得する

このエンドポイントでは、既知のすべてのテンプレートの一覧を返します。

HTTP GET https://templates.adaptivecards.io/list

応答 (抜粋)

{
  "graph.microsoft.com": {
    "templates": [
      {
        "file": "Files.json",
        "fullPath": "graph.microsoft.com/Files.json"
      },
      {
        "file": "Profile.json",
        "fullPath": "graph.microsoft.com/Profile.json"
      }
   ]
}

テンプレートを見つける

このエンドポイントでは、データの構造を分析することにより、テンプレートの検索を試みます。

HTTP POST https://templates.adaptivecards.io/find

例

自分に関する組織データを取得するため、Microsoft Graph エンドポイントにアクセスしたとします。

HTTP GET https://graph.microsoft.com/v1.0/me/

Graph Explorer screenshot

その API は JSON データを返します。では、アダプティブ カードを使用してユーザーにそのデータを表示するにはどうすればよいでしょうか。

まず、この種類のデータのためのテンプレートが存在するかどうかを確認します。そのため、POST body に含まれる自分のデータを使用して、/find エンドポイントに HTTP 要求を送信します。

HTTP POST https://templates.adaptivecards.io/find

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "businessPhones": [
        "+1 412 555 0109"
    ],
    "displayName": "Megan Bowen",
    "givenName": "Megan",
    "jobTitle": "Auditor",
    "mail": "MeganB@M365x214355.onmicrosoft.com",
    "mobilePhone": null,
    "officeLocation": "12/1110",
    "preferredLanguage": "en-US",
    "surname": "Bowen",
    "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
    "id": "48d31887-5fad-4d73-a9f5-3c356e68a038"
}

応答:

[
  {
    "templateUrl": "graph.microsoft.com/Profile.json",
    "confidence": 1
  }
]

サービスは、一致するテンプレートの一覧と、一致の度合いを示す confidence を返します。 これで、そのテンプレート URL を使用してテンプレートを取得したり、サーバー側で設定したりできます。

テンプレートの取得

このエンドポイントから取得したテンプレートには、テンプレート SDK を使用して、実行時にデータを設定できます。

HTTP GET https://templates.adaptivecards.io/[TEMPLATE-PATH]

テンプレートに "サンプル データ" を含めることもできます。この機能を使用すると、デザイナーでの編集が容易になります。

HTTP GET https://templates.adaptivecards.io/[TEMPLATE-PATH]?sampleData=true

例

上の /find で返された Microsoft Graph プロファイル テンプレートを取得してみましょう。

HTTP GET https://templates.adaptivecards.io/graph.microsoft.com/Profile.json

応答 (抜粋)

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "{name}"
    },
    {
        // ...snip
    }
  ]
}

今度は、テンプレート SDK でこのテンプレートを使用して、すぐにレンダリングできるアダプティブ カードを作成します。

テンプレートをサーバー側で設定する

クライアントでテンプレートを設定することが合理的でない場合があります。 それらの場合、完全に設定され、アダプティブ カード レンダラーに渡す準備が済んでいるアダプティブ カードをサービスによって返すようにできます。

HTTP POST https://templates.adaptivecards.io/[TEMPLATE-PATH]

例

上のデータを使用して、/find から返された Microsoft Graph プロファイル テンプレートを設定してみましょう。

HTTP POST https://templates.adaptivecards.io/graph.microsoft.com/Profile.json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "businessPhones": [
        "+1 412 555 0109"
    ],
    "displayName": "Megan Bowen",
    "givenName": "Megan",
    "jobTitle": "Auditor",
    "mail": "MeganB@M365x214355.onmicrosoft.com",
    "mobilePhone": null,
    "officeLocation": "12/1110",
    "preferredLanguage": "en-US",
    "surname": "Bowen",
    "userPrincipalName": "MeganB@M365x214355.onmicrosoft.com",
    "id": "48d31887-5fad-4d73-a9f5-3c356e68a038"
}

応答 (抜粋)

{
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [
    {
      "type": "TextBlock",
      "size": "Medium",
      "weight": "Bolder",
      "text": "Megan Bowen"
    },
    {
        // ...snip
    }
  ]
}

応答で、最初の TextBlock のテキストが、GET 要求の場合の "{name}" ではなく、"Megan Bowen" に置き換えられていることにご注目ください。 このアダプティブ カードは、クライアント側でテンプレート処理せずに、任意のアダプティブ カード レンダラーに渡すことができるようになりました。

テンプレートの投稿

テンプレートは adaptivecards-templates リポジトリの GitHub でホストされています。

Microsoft では、GitHub をテンプレートのバッキング ストアとして使用することで、テンプレートの作成、拡張、共有というプロセスを "民主化" したいと考えています。 誰でも、まったく新しいテンプレートを含む pull request の送信や、既存のテンプレートの拡張ができ、しかも、そのすべてを GitHub の開発者フレンドリなエクスペリエンスで実現できます。

サービスをセルフホストする

データの種類によっては、https://templates.adaptivecards.io で "一元的に" ホストされるアダプティブ カード テンプレート サービスに向かないものもあります。

Microsoft では、誰でもこのテンプレート サービスを自分の組織内でホストできるようにしたいと考えているため、ソース コードを GitHub で公開し、自分の Azure Function に簡単に展開できるようになっています。

ここから開始➡ adaptivecards-templates