スキーマ拡張機能を使用したグループへのカスタム データの追加

このチュートリアルでは、 スキーマ拡張機能の使用方法について説明します。

ローズカレッジ というラーニングマネジメントソフトウェア会社の開発者で、企業向けのトレーニングコースと教材を構築しているとします。 Microsoft 365 グループのコラボレーション エクスペリエンスを使用して、オンライン コースとインストラクター主導のコースの両方の参加者間でコース コンテンツを配信し、演習を記録します。 トレーニング コースに使用される Microsoft 365 グループをトレーニング コースとして簡単に識別できるようにする必要があります。これにより、他の開発者がグループを検出し、学習コースの上に豊富なエクスペリエンスを構築できます。

このシナリオでは、次の方法について説明します。

  • 使用できるスキーマ拡張機能の定義を確認します。
  • トレーニング コースの対象グループに適用されるスキーマ拡張機能の定義を登録する
  • 登録したスキーマ拡張定義に基づいて、カスタム データを含む新しいグループを作成します。
  • スキーマ拡張機能の定義に基づいて既存のグループのカスタム データを追加、更新または削除する
  • グループと拡張データを読み取る。
  • スキーマ拡張定義と拡張データを削除します。

注:

グループとは別に、スキーマ拡張機能もサポートされており、 他のリソースの種類に対して管理できます。

前提条件

この記事の手順を再現するには、次の特権が必要です。

  • Graph エクスプローラーなどの API クライアントにサインインします。
  • サインインしているユーザーに対して Group.ReadWrite.AllApplication.ReadWrite.All 委任されたアクセス許可をアプリに付与します。
  • このチュートリアルでスキーマ拡張機能定義の所有権を割り当てるアプリケーションの所有者であること。 このチュートリアルでは、アプリケーションは extensions-application という名前で、 appId を持っていますd1e6f196-fca3-48ad-8cd3-1a98e3bd46d2

手順 1. 使用可能なスキーマ拡張機能を表示する

最初に、開発者は、既存のスキーマ拡張定義が目的に合っている場合に、アプリで再利用することが必要になる場合があります。 次の例では、 という名前のスキーマ拡張機能に対してクエリを実行します (ID によって)。 bellowscollege_courses 応答で、テナントに名前が付けられた bellowscollege_courses スキーマ拡張機能がないことを示しているとします。

要求

GET https://graph.microsoft.com/v1.0/schemaExtensions?$filter=id eq 'bellowscollege_courses'

応答

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#schemaExtensions",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET schemaExtensions?$select=description,owner",
    "value": []
}

次のようにGET https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses、パス パラメーターとして id を使用してクエリを実行することもできます。 ID と一致するスキーマ拡張機能がない場合、応答は です 404 Not Found

手順 2. スキーマ拡張定義を登録する

グループ リソースのトレーニング コースの新しい拡張機能定義を作成して登録する必要があります。 次のプロパティを指定します。

  • id: 次の 2 つの方法のいずれかに従って、このプロパティの文字列を指定します。
    • オプション 1: テナントの 検証済 みバニティ ドメイン名とスキーマ拡張機能の名前を連結します。 たとえば、ドメインが で bellowscollege.com、スキーマ拡張機能の名前が である場合は coursesIDbellowscollege_courses を使用できます。

    • オプション 2: 別の方法として、 などの coursesスキーマ名のみを指定し、指定された名前の前にランダムな英数字文字列を付けることによって、Microsoft Graph に自動的に ID を 生成させる方法があります。

      この ID は、グループのスキーマ拡張プロパティの名前になります。

  • description
  • targetTypes: スキーマ拡張機能を適用できるリソースの種類を指定します。 この例では、リソースの種類は です Group。 後でスキーマ拡張機能の定義を更新することで、さらにリソースの種類を追加できます。
  • properties: スキーマを構成するカスタム プロパティを指定します。 この例では、courseIdcourseName、および courseType カスタム プロパティとその種類を指定します。 スキーマ拡張定義を作成した後は、追加の変更のみが許可されます。
  • owner: スキーマ拡張定義を所有するアプリケーションを指定します。 所有者として割り当てられないアプリからこの例を実行している場合は、所有者プロパティで割り当てられているアプリケーションの appId を指定します。

要求

POST https://graph.microsoft.com/v1.0/schemaExtensions
Content-type: application/json

{
    "id": "bellowscollege_courses",
    "description": "Bellows College training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "owner": "d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

応答

次の例は応答を示しています。

応答では、スキーマ拡張機能の既定の初期状態は です InDevelopment。 拡張機能を開発している間は、この状態を維持できます。その間、追加の変更で更新したり、削除したりできるのは、その拡張機能を作成したアプリだけです。 他のアプリで使用する拡張機能を共有する準備ができたら、 状態[使用可能] に設定します。

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#schemaExtensions/$entity",
    "id": "bellowscollege_courses",
    "description": "Bellows College training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "status": "InDevelopment",
    "owner": "d1e6f196-fca3-48ad-8cd3-1a98e3bd46d2",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

手順 3. カスタム データを使用してグループを拡張する

グループの作成時または既存のグループを更新することで、カスタム データを使用してグループを拡張できます。

オプション 1: 拡張データを含む新しいグループを作成する

次の要求では、新しいグループを作成し、スキーマ拡張機能を bellowscollege_courses 使用してカスタム データを使用してグループを拡張します。 既存のグループがある場合は、拡張データを使用してグループを更新することで、カスタム データで拡張することもできます。

応答では、データ拡張機能ミラー返されません。 操作を使用して、名前で明示的に $select 拡張機能を指定する必要があります GET /group/{id}

要求

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
    "displayName": "New Managers March 2024",
    "description": "New Managers training course for March 2024",
    "groupTypes": [
        "Unified"
    ],
    "mailEnabled": true,
    "mailNickname": "newMan202403",
    "securityEnabled": false,
    "bellowscollege_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Online"
    }
}

応答

次の例は応答を示しています。 応答に新しい拡張機能は含まれません。 操作を使用して、名前で明示的に $select 拡張機能を指定する必要があります GET /group/{id}

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "8fb45944-4085-449f-b95d-f7dd74a1b081",
    "createdDateTime": "2024-01-24T09:09:03Z",
    "description": "New Managers training course for March 2024",
    "displayName": "New Managers March 2024",
    "groupTypes": [
        "Unified"
    ],
    "mail": "newMan202403@bellowscollege.com",
    "mailEnabled": true,
    "mailNickname": "newMan202403"
}

オプション 2: 拡張データを使用して既存のグループを更新する

既存のグループがある場合は、次のようにカスタム データを使用して拡張することもできます。 要求は応答を 204 No Content 返します。

PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json

{
    "bellowscollege_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Online"
    }
}

手順 4. グループ内のカスタム データを更新する

次の要求は、グループの拡張機能の courseType プロパティを bellowscollege_coursesHybrid更新します。 courseType プロパティのみを更新する必要がありますが、他のプロパティとその既存の値も要求本文に含める必要があります。 それ以外の場合、Microsoft Graph はデータを に null 設定し、そのデータを削除します。

次の要求は応答を 204 No Content 返します。

PATCH https://graph.microsoft.com/v1.0/groups/dfc8016f-db97-4c47-a582-49cb8f849355
Content-type: application/json

{
    "bellowscollege_courses": {
        "courseId": "123",
        "courseName": "New Managers",
        "courseType": "Hybrid"
    }
}

手順 5. グループとその拡張データを取得する

グループ内のカスタム データを取得するには、 を使用 $select して拡張子を名前で含めます。

スキーマ拡張機能の ID によるフィルター処理とは別に、拡張プロパティの値でフィルター処理することもできます。 次の例では、プロパティ値が と一致123する拡張機能を持bellowscollege_coursesつグループをcourseId検索し、拡張データと、グループの displayNameidおよび description プロパティを取得します。

要求

GET https://graph.microsoft.com/v1.0/groups?$filter=bellowscollege_courses/courseId eq '123'&$select=displayName,id,description,bellowscollege_courses

応答

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups(displayName,id,description,bellowscollege_courses)",
    "value": [
        {
            "displayName": "New Managers March 2024",
            "id": "8fb45944-4085-449f-b95d-f7dd74a1b081",
            "description": "New Managers training course for March 2024",
            "bellowscollege_courses": {
                "@odata.type": "#microsoft.graph.ComplexExtensionValue",
                "courseType": "Hybrid",
                "courseName": "New Managers",
                "courseId": 123
            }
        }
    ]
}

手順 6: 拡張データとスキーマ拡張定義を削除する

必要がなくなった場合は、スキーマ拡張定義を削除できます。 リソース インスタンスに拡張プロパティが適用されている場合、スキーマ拡張定義を削除しても、リソース インスタンス内の拡張データは削除されません。 代わりに、拡張機能データは使用できますが、アクセスできなくなります。 スキーマ拡張 ID の検証済みドメインを使用した場合は、同じ構成でスキーマ拡張機能定義を再作成して、拡張データを削除できます。

次の要求は、 bellowscollege_courses スキーマ拡張プロパティとその関連データをグループから削除します。 要求は応答を 204 No Content 返します。

PATCH https://graph.microsoft.com/v1.0/groups/8fb45944-4085-449f-b95d-f7dd74a1b081

{
    "bellowscollege_courses": null
}

次の要求は、スキーマ拡張定義を bellowscollege_courses 削除します。 要求は応答を 204 No Content 返します。

DELETE https://graph.microsoft.com/v1.0/schemaExtensions/bellowscollege_courses