アダプティブ カード テンプレート サービスAdaptive Cards Template Service

アダプティブ カード テンプレート サービスは、一連の既知のテンプレートをだれでも検索、投稿、共有できるようにする概念実証サービスです。The Adaptive Cards Template Service is a proof-of-concept service that allows anyone to find, contribute to, and share a set of well-known templates.

一部のデータを表示する必要があるものの、そのためにカスタムのアダプティブ カードを作成するのが面倒な場合に便利です。It's useful if you want to display some data but don't want to bother writing a custom adaptive card for it.

アダプティブ カード テンプレートの概要については、こちらをお読みください。Please read this for an overview of Adaptive Card Templating

重要

使用条件Terms and agreement

このアルファレベル サービスは、エラーを含めて現状のまま提供されており、いかなるサポートも提供されません。This alpha-level service is provided "as-is", with all faults and is not supported in any way. 本サービスからのデータ収集には、Microsoft プライバシー ステートメントが適用されます。Any data collection from the service is subject to the Microsoft privacy statement.

これらの機能はプレビュー段階であり、変更される可能性がありますThese features are in preview and subject to change. フィードバックは歓迎されるだけでなく、ユーザーが必要とする機能を確実に提供するために不可欠です。Your feedback is not only welcome, but critical to ensure we deliver the features you need.

このサービスがどのように役立つかHow does the service help me?

財務データ、Microsoft Graph データ、schema.org データ、組織内のカスタム データなど、何らかのデータを入手したとします。Let's say I just got a piece of data, maybe it's financial data, Microsoft Graph data, schema.org data, or custom data from within my organization.

そのデータをユーザーに示す必要がある場合、Now I want to display the data to a user.

これまでは、エンドユーザーに配信するすべてのフロントエンド スタックにカスタム UI コードを記述する必要がありました。Traditionally that means writing custom UI code in all of the front-end stacks that I deliver to end-users.

では、アプリ自体がデータの種類に基づいて新しい UI テンプレートを "学習" できるとしたらどうでしょうか。But what if there were a world where my app could "learn" new UI templates based on the type of data? 自分のプロジェクト内、組織内、またはインターネット全体で、すべてのユーザーが共通の UI テンプレートを投稿、拡張、共有できる場合です。A world where anyone could contribute, enhance, and share common UI templates, within their own projects, within an organization, or for the entire internet.

カード テンプレート サービスとはWhat is the card template service?

カード テンプレート サービスは、単純な REST エンドポイントで、次のことに役立ちます。The card template service is a simple REST endpoint that helps:

  • データの構造を分析してテンプレートを検索しますFind a template by analyzing the structure of your data
  • テンプレートを取得して、クライアントに直接バインドできます。データをサーバーに送信したり、デバイスを離れたりしないで済みますGet a template so you can bind it directly on the client, without sending your data to the server or ever leaving the device
  • クライアント側でのデータ バインディングが不適切または不可能である場合、サーバー上でテンプレートを設定しますPopulate a template on the server, when client-side data binding isn't appropriate or possible

これには次のことが関係しています。Behind it all, is:

  • GitHub によってサポートされるオープンソースの共有テンプレート リポジトリ。A shared, open-source template repository backed by GitHub. (リポジトリは現在非公開ですが、いくつかの細かな処理が済み次第公開されます)(The repo is currently private but will be made public as soon as we tie up some loose ends)
  • すべてのテンプレートが、このリポジトリに含まれるフラットな JSON ファイルです。このため、開発者ワークフローの自然な一部として編集、投稿、共有を行なえます。All the templates are flat JSON files in the repo, which makes editing, contributing, and sharing a natural part of a developer workflow.
  • サービスのコードが利用できるようになります。これにより、ユーザーが最も利用しやすい場所でホストできます。The code for the service will be made available so you can host wherever makes the most sense to you.

サービスの使用Using the service

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

このエンドポイントでは、既知のすべてのテンプレートの一覧を返します。This endpoint returns a list of all known templates.

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

応答 (抜粋)Response excerpt

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

テンプレートを検索するFind a template

このエンドポイントでは、データの構造を分析することにより、テンプレートの検索を試みます。This endpoint tries to find a template by analyzing the structure of your data.

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

Example

自分に関する組織データを取得するため、Microsoft Graph エンドポイントにアクセスしたとします。Let's say I access a Microsoft Graph endpoint to get organizational data about me.

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

Graph エクスプローラーのスクリーンショット

その API は JSON データを返します。では、アダプティブ カードを使用してユーザーにそのデータを表示するにはどうすればよいでしょうか。That API returned JSON data, but how do I display it to users using Adaptive Cards?

まず、この種類のデータのためのテンプレートが存在するかどうかを確認します。そのため、POST body に含まれる自分のデータを使用して、/find エンドポイントに HTTP 要求を送信します。First I want to see if a template exists for this type of data, so I make an HTTP request to the /find endpoint with my data in the POST body.

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"
}

応答:Response:

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

サービスは、一致するテンプレートの一覧と、一致の度合いを示す confidence を返します。The service returns a list of any matching templates, along with a confidence indicating how close the match is. これで、そのテンプレート URL を使用してテンプレートを取得したり、サーバー側で設定したりできます。Now I can use that template URL to get the template, or populate it server-side.

テンプレートを取得するGet a template

このエンドポイントから取得したテンプレートには、テンプレート SDK を使用して、実行時にデータを設定できます。A template retrieved from this endpoint can be populated with data at runtime using the templatng SDKs.

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

テンプレートに "サンプル データ" を含めることもできます。この機能を使用すると、デザイナーでの編集が容易になります。You can also include "sample data" with the template, which makes editing in the designer more friendly:

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

Example

上の /find で返された Microsoft Graph プロファイル テンプレートを取得してみましょう。Let's get the Microsoft Graph profile template that was returned from /find above.

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

応答 (抜粋)Response excerpt

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

今度は、テンプレート SDK でこのテンプレートを使用して、すぐにレンダリングできるアダプティブ カードを作成します。Now use this template with the templating SDKs to create a ready-to-render Adaptive Card.

テンプレートをサーバー側で設定するPopulate a template server-side

クライアントでテンプレートを設定することが合理的でない場合があります。In some cases it may not make sense to populate a template on the client. それらの場合、完全に設定され、アダプティブ カード レンダラーに渡す準備が済んでいるアダプティブ カードをサービスによって返すようにできます。For these use cases, you can have the service return a fully-populated Adaptive Card, ready to be passed to any Adaptive Card Renderer.

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

Example

上のデータを使用して、/find から返された Microsoft Graph プロファイル テンプレートを設定してみましょう。Let's populate the Microsoft Graph profile template that was returned from /find using the data above.

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"
}

応答 (抜粋)Response excerpt

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

応答で、最初の TextBlock のテキストが、GET 要求の場合の "{name}" ではなく、"Megan Bowen" に置き換えられていることにご注目ください。Notice how the response replaced the text of the first TextBlock with "Megan Bowen" instead of "{name}", as in the GET request. このアダプティブ カードは、クライアント側でテンプレート処理せずに、任意のアダプティブ カード レンダラーに渡すことができるようになりました。This AdaptiveCard can now be passed to any Adaptive Card renderer without going through client-side templating.

テンプレートの投稿Contributing templates

テンプレートは adaptivecards-templates リポジトリの GitHub でホストされています。The templates are hosted on GitHub in the adaptivecards-templates repo.

Microsoft では、GitHub をテンプレートのバッキング ストアとして使用することで、テンプレートの作成、拡張、共有というプロセスを "民主化" したいと考えています。Our hope is that by using GitHub as a backing store for the templates, we can "democratize" the process of authoring, enhancing, and sharing templates. 誰でも、まったく新しいテンプレートを含む pull request の送信や、既存のテンプレートの拡張ができ、しかも、そのすべてを GitHub の開発者フレンドリなエクスペリエンスで実現できます。Anyone can submit a Pull Request that includes an entirely new template, or make enhancements to existing ones... all within the developer-friendly experience of GitHub.

サービスをセルフホストするSelf-hosting the service

データの種類によっては、https://templates.adaptivecards.io で "一元的に" ホストされるアダプティブ カード テンプレート サービスに向かないものもあります。Not all types of data are appropriate for the "central" Adaptive Cards template service hosted at https://templates.adaptivecards.io.

Microsoft では、誰でもこのテンプレート サービスを自分の組織内でホストできるようにしたいと考えているため、ソース コードを GitHub で公開し、自分の Azure Function に簡単に展開できるようになっています。We want to make sure anyone can host the template service within your organization, so the source code is available on GitHub and can be easily deployed to your own Azure Function.

ここから開始➡ adaptivecards-templatesGet started here ➡ adaptivecards-templates