スキーマ拡張機能を使用したグループへのカスタム データの追加Add custom data to groups using schema extensions

スキーマ拡張機能の使用方法について、具体例を使って説明します。We're going to walk you through an example to demonstrate how to use schema extensions.

ここでは、企業向けトレーニングのコースや教材を製作する “Graph Learn” という名前の学習管理ソフトウェア会社で開発者として働いているとしましょう。充実した共同エクスペリエンスを備えた Office 365 グループは、オンライン コースの参加者および講師が指導するコースの参加者どちらに対しても、コース コンテンツを配信したりエクササイズの記録をとったりするのに最適なツールです。トレーニング コースのために使う Office 365 グループを、トレーニング コースとしてすぐに見分けがつくようにしておくと、他の開発者がグループを見つけやすくなり、学習コースに基づいて豊富なエクスペリエンスを構築するのに役立ちます。Imagine you're a developer in a Learning Management Software company called “Graph Learn” that builds training courses and materials for businesses. Office 365 groups, with their rich collaborative experiences, is a fantastic way to deliver course content and record exercises among participants for both online courses and instructor-led courses. You may want to make those Office 365 groups used for training courses easily identifiable as training courses, which will allow other developers to discover your groups and build rich experiences on top of your learning courses.

このシナリオでは、以下の操作を行う方法を紹介します。For this scenario, we're going to show you how to:

  1. 利用可能なスキーマ拡張機能の定義を確認するView available schema extension definitions that you could use.
  2. トレーニング コースの対象グループに適用されるスキーマ拡張機能の定義を登録するRegister a schema extension definition that targets groups for training courses.
  3. 登録したスキーマ拡張機能の定義に基づいた拡張データで新しいグループを作成するCreate a new group with extended data based on the schema extension definition that you just registered.
  4. スキーマ拡張機能の定義に基づいて既存のグループのカスタム データを追加、更新または削除するAdd, update, or remove custom data in an existing group based on a schema extension definition.
  5. グループと拡張機能データを読み取るRead back a group and the extension data.

注: このトピックでは、グループ リソースでスキーマ拡張機能の値を作成し、読み取る方法について説明します (手順 3 から 5)。同じメソッドは、** administrativeUnit**、デバイスイベントメッセージ組織、**投稿**、および ユーザー リソースの種類でもサポートされています。このため、これらのリソースのいずれかで、下にある要求例と同様の操作を実行できます。注: administrativeUnit はベータ版エンドポイントでのみ使用可能です。Note: This topic shows you how to create and read schema extension values on a group resource (steps 3-5). The same methods are supported for the administrativeUnit, device, event, message, organization, post, and user resource types as well. So you can carry out similar operations as the example requests below on any of those resources. Note that administrativeUnit is available only in the beta endpoint.

1.利用可能なスキーマ拡張機能を確認する1. View available schema extensions

開発者は、まずアプリで再利用できるスキーマ拡張機能の定義が他にないか調べる必要があります。これは schemaExtension リソースをクエリすることによって可能です。First, as a developer, you might want to find any other schema extension definitions that our app could reuse. This can be done by querying the schemaExtension resource.
次の例では、特定のスキーマ拡張機能を id でクエリします。In the example below, you're going to query for a specific schema extension by id.

応答で返される拡張機能の状態値は Available であることに注意してください。これは、targetTypes プロパティのリソースへのアクセス許可を持つ任意のアプリが、拡張機能を使用でき、付加的な変更で拡張機能を更新できることを示しています。通常、この操作では、状態にかかわらず、指定されたフィルターに一致するすべてのスキーマ拡張機能が返されるため、使用する前に拡張機能の状態を必ず確認してください。Notice that the extension returned in the response has Available as the status value, which indicates that any app which has permission to the resources in the targetTypes property can use and update the extension with additive changes. In general, this operation returns any schema extensions that satisfy the specified filter regardless of status, so do check the extension status before using it.

要求Request
GET https://graph.microsoft.com/v1.0/schemaExtensions?$filter=id eq 'graphlearn_test'
応答Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-length: 420
{
    "value": [
        {
            "id":"graphlearn_test",
            "description": "Yet another test schema",
            "targetTypes": [
                "User", "Group"
            ],
            "status": "Available",
            "owner": "24d3b144-21ae-4080-943f-7067b395b913",
            "properties": [
                {
                    "name": "testName",
                    "type": "String"
                }
            ]
        }
    ]
}

2.トレーニング コースについて説明するスキーマ拡張機能の定義を登録する2. Register a schema extension definition that describes a training course

ニーズに適したスキーマ拡張機能が見つからない場合は、グループ リソースでトレーニング コースの新しい拡張機能の定義を作成し登録します。If you can't find a schema extension that is appropriate for your needs, you can create and register a new extension definition for training courses on the group resource.

スキーマ拡張機能定義を作成する場合、id プロパティに文字列を指定する必要があります。これを実行するには、次の 2 つの方法があります。次の例は優先される方法を示しています。この方法では、ご使用のテナントで検証済みのバニティ ドメイン名 (graphlearn.com) を使用します。検証済みドメイン名 (graphlearn) とスキーマ拡張機能名 (courses) を連結し、連結後の文字列 graphlearn_courses を使用して ID を割り当てます。When creating a schema extension definition, you should provide a string for the id property. There are two ways to do this. The following example shows the preferred way, which uses a vanity domain name (graphlearn.com) that has been verified with your tenant. Concatenate the verified domain name (graphlearn) with a name for the schema extension (courses), and assign id with the resultant string, graphlearn_courses.

説明 (見つけやすくするため)、(この拡張機能が適用されるリソースを定義する) 対象の種類、およびスキーマを構成するカスタム プロパティも指定します。この例の場合、courseIdcourseNamecourseType のカスタム プロパティとその種類を指定します。Then, specify a description (to enable discoverability), target types (defining which resources this extension applies to), and the custom properties that make up the schema. In this example, specify the courseId, courseName and courseType custom properties and their types.

要求で ID を割り当てる他の方法の例を参照してください。この例で必要となるのは、スキーマ名の指定のみです。See an example of the other way to assign id in the request, that requires you to provide only a schema name.

スキーマ拡張機能を最初に作成するとき、その状態は InDevelopment であることに注意してください。拡張機能の開発中は、この状態を保持できます。その間、拡張機能を付加的な変更で更新したり、削除したりできるのは拡張機能を作成したアプリだけです。他のアプリで使用するために拡張機能を共有する準備ができたら、statusAvailable に設定します。Notice that when you initially create a schema extension, its status is InDevelopment. While you're developing the extension, you can keep it in this status, during which only your app that created it can update it with additive changes or delete it. When you are ready to share the extension for use by other apps, set status to Available.

要求Request
POST https://graph.microsoft.com/v1.0/schemaExtensions
Content-type: application/json
{
    "id":"graphlearn_courses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}
応答Response
HTTP/1.1 201 Created
Content-Type: application/json
Content-length: 420
{
    "id": "graphlearn_courses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "status": "InDevelopment",
    "owner": "24d3b144-21ae-4080-943f-7067b395b913",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

3.拡張データを含む新しいグループを作成する3. Create a new group with extended data

_新しい_グループを作成し、登録したばかりの graphlearn_courses スキーマ拡張機能定義を使って、追加のデータでグループを拡張します。これは、グループ リソースへの標準的な POST と、要求本文で定義された追加の graphlearn_courses の複合型の拡張機能です。応答では、データ拡張機能を返しません。GET 操作を使用して、名前により拡張機能を明示的に $select する必要があります。Create a new group and extend it with extra data using the graphlearn_courses schema extension definition that we just registered. This is a standard POST to the group resource, with the additional graphlearn_courses complex type extension defined in the request body. The response will not mirror back any data extensions. We need to explicitly $select the extension by name using a GET operation.

要求Request
POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json
{
    "displayName": "New Managers March 2017",
    "description": "New Managers training course for March 2017",
    "groupTypes": ["Unified"],
    "mailEnabled": true,
    "mailNickname": "newMan201703",
    "securityEnabled": false,
    "graphlearn_courses": {
        "courseId":"123",
        "courseName":"New Managers",
        "courseType":"Online"
    }
}
応答Response
HTTP/1.1 201 Created
Content-Type: application/json
Content-length: 420
{
    "id": "dfc8016f-db97-4c47-a582-49cb8f849355",
    "createdDateTime": "2017-02-09T00:17:05Z",
    "description": "New Managers training course for March 2017",
    "displayName": "New Managers March 2017",
    "groupTypes": [
        "Unified"
    ],
    "mail": "newMan201703@graphlearn.com",
    "mailEnabled": true,
    "mailNickname": "newMan201703",
    "securityEnabled": false,
    "theme": null,
    "visibility": "Public"
}

4.既存のグループのカスタム データを追加、更新、または削除します。4. Add, update, or remove custom data in an existing group

PATCH 要求の本文で定義した追加の graphlearn_courses の複合型の拡張機能を使って、カスタム データを拡張し、_既存_のグループ インスタンスに追加することができます。You can extend and add custom data to an existing group instance with the additional graphlearn_courses complex type extension defined in the body of a PATCH request.

要求Request
PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json
Content-length: 230
{
    "graphlearn_courses":{
        "courseId":"123",
        "courseName":"New Managers",
        "courseType":"Online"
    }   
}
応答Response
HTTP/1.1 204 No Content

拡張機能データの値を更新する場合は、複合型拡張機能の全体を PATCH 要求の本文に置きます (既存のリソースにカスタム データを追加するのと同様)。If you want to update the values of the extension data, put the entire extension complex type in the body of a PATCH request (similar to adding custom data to an existing resource).

対応する拡張機能のプロパティを Null に設定することで、リソース インスタンスに追加されたカスタム データを削除できます。You can also remove custom data added to a resource instance by setting the corresponding extension property to null.

リソース インスタンスからスキーマ拡張機能を削除する場合、当該インスタンスの複合型拡張機能を Null に設定します。To remove a schema extension from a resource instance, set the extension complex type in that instance to null.

5.グループとその拡張機能データを取得する5. Get a group and its extension data

拡張機能の名前や ID など特定の拡張機能のプロパティ値に一致する $filter を使用すると簡単にグループ (または複数のグループ) を検索できます。A handy way to look for a group (or groups) is to use $filter to match for specific extension property values, such as an extension name or ID.

次に、$select を使って、拡張機能の名前を指定し (この場合は graphlearn_courses)、グループのカスタムデータを取得します。Then, to get the custom data in a group, use $select to include the extension by name (in this case by graphlearn_courses).

次の例では、graphlearn_courses の拡張機能と 123 に一致する courseId のプロパティ値を有するグループを検索し、graphlearn_courses 拡張機能のグループのプロパティ、displayNameID説明、カスタム データを取得します。(実際のクエリでは、必要に応じて URL エンコードを行ってください。)The following example looks for the group that has the graphlearn_courses extension with a courseId property value matching 123, and gets the group properties displayName, id, and description, and the custom data in the graphlearn_courses extension. (In the actual query, make sure you apply URL encoding as necessary.)

要求Request

GET https://graph.microsoft.com/v1.0/groups?$filter=graphlearn_courses/courseId eq ‘123’&$select=displayName,id,description,graphlearn_courses
応答Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-length: 326
{
  "value": [
    {
      "displayName": "New Managers March 2017",
      "id": "14429ae5-3e74-41a2-9fa8-028fbb984637",
      "description": "New Managers training course for March 2017",
      "graphlearn_courses": {
        "@odata.type": "#microsoft.graph.ComplexExtensionValue",
        "courseId":"123",
        "courseName":"New Managers",
        "courseType":"Online"
      }
    }
  ]
}

関連項目See also