次の方法で共有


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

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

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

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

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

注:

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

前提条件

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

  • Graph Explorer などの API クライアントにサインインします。
  • サインインしているユーザーに対して Group.ReadWrite.AllApplication.ReadWrite.All 委任されたアクセス許可をアプリに付与します。
  • このチュートリアルでスキーマ拡張機能定義の所有権を割り当てるアプリケーションの所有者であること。 このチュートリアルでは、アプリケーションは extensions-application という名前で、 appIdd1e6f196-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": []
}

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

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

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

  • id: 次の 2 つの方法のいずれかに従って、このプロパティの文字列を指定します。
    • オプション 1: テナントの 検証済 みバニティ ドメイン名とスキーマ拡張機能の名前を連結します。 たとえば、ドメインが bellowscollege.comで、スキーマ拡張機能の名前が coursesされている場合は、 idbellowscollege_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 スキーマ拡張機能を使用して、カスタム データを使用してグループを拡張します。 既存のグループがある場合は、拡張データを使用してグループを更新することで、カスタム データで拡張することもできます。

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

要求

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

応答

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

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

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. グループ内のカスタム データを更新する

次の要求により、グループのbellowscollege_courses拡張機能の courseType プロパティがHybridに更新されます。 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に一致するcourseId プロパティ値を持つbellowscollege_courses拡張子を持つグループを検索し、そのグループの拡張データと 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