schemaExtension の作成

名前空間: microsoft.graph

サポートするリソースの種類を拡張するために、schemaExtension 定義を新規作成します。

スキーマ拡張機能により、厳密に型指定されたカスタム データをリソースに追加することができます。スキーマ拡張機能を作成するアプリは、所有者アプリです。拡張機能の状態によっては、拡張機能を更新または削除できるのは、所有者アプリだけです。

トレーニング コースを説明するスキーマ拡張機能を定義する方法、スキーマ拡張定義を使用してトレーニング コース データで新規グループを作成する方法、既存グループにトレーニング コース データを追加する方法については、それぞれの例を参照してください。

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。

アクセス許可の種類 アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント) Application.ReadWrite.All
委任 (個人用 Microsoft アカウント) サポートされていません。
アプリケーション Application.ReadWrite.All and Directory.ReadWrite.All

注意

また、委任されたフローの場合は、サインインしているユーザーが、呼び出し元アプリケーションの所有者であるか、所有者 プロパティの設定に使用する appId を持つアプリケーションの所有者である必要があります。

HTTP 要求

POST /schemaExtensions

要求ヘッダー

名前 説明
Authorization ベアラー {token}。必須。
Content-Type application/json

要求本文

要求本文では、schemaExtension オブジェクトの JSON 表記を指定します。

次の表に、スキーマ拡張機能の作成時に必要なプロパティを示します。

パラメーター 説明
description String スキーマ拡張機能の説明。
id String スキーマ拡張機能の定義の一意の識別子。
値の割り当ては、以下の 2 方法のいずれかで行うことができます。
  • 確認されたドメインの内の 1 つの名前とスキーマ拡張機能の名前を連結して、{domainName}_{schemaName} という形式の一意の文字列を形成します。 次に例 contoso_mySchema を示します。 注: 上位ドメイン .com.net.gov.edu.org の下では、検証済みのドメインのみがサポートされます。
  • スキーマ名を指定し、Microsoft Graph がそのスキーマ名を使用して id 割り当てを完了するには、次の形式を使用します。ext{8-random-alphanumeric-chars}_{schema-name}。たとえば、extkvbmkofy_mySchema です。
作成後、このプロパティは変更できません。
owner String (省略可能) スキーマ拡張機能の所有者であるアプリケーションの appId です。 既定では、呼び出し元アプリケーションの appId が owner として設定されます。 ただし、このプロパティは、owner appId を呼び出し元アプリとは異なるものに設定するように作成時に指定することができます。 いずれの場合も、委任されたフローでは、サインインしたユーザーが、スキーマ拡張機能の所有者として設定されるアプリケーションの所有者である 必要があります。 たとえば、Graph エクスプローラーを使用して新しいスキーマ拡張機能の定義を作成する場合は、owner プロパティを、所有している appId に指定する 必要があります。 設定すると、このプロパティは読み取り専用で、変更することはできません。
properties extensionSchemaProperty コレクション スキーマ拡張機能の定義を構成するプロパティの名前と種類のコレクション。
targetTypes String collection このスキーマ拡張機能の定義を適用できる、(スキーマ拡張機能をサポートしている) 一連の Microsoft Graph のリソースの種類。

応答

成功した場合、このメソッドは応答本文で 201 Created 応答コードと、schemaExtension オブジェクトを返します。

例 1: 確認済みのドメインを使用してスキーマ拡張機能を作成する

要求

この例では、検証済みのドメイン名、graphlearn、およびスキーマ名 courses を使用して、スキーマ拡張定義の ID プロパティの一意の文字列を形成する方法を示します。一意の文字列は、この形式、{domainName}_{schemaName} に基づいています。

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

応答

応答の例を次に示します。

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

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

{
    "id": "graphlearn_courses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "status": "InDevelopment",
    "owner": "24d3b144-21ae-4080-943f-7067b395b913",
    "properties": [
        {
            "name": "courseId",
            "type": "String"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

例 2: 名前のみを使用してスキーマ拡張機能を作成する

要求

この例では、要求の ID プロパティ内のスキーマ名 courses だけを指定し、schemaExtension オブジェクト内の残りのプロパティを JSON 表記で指定しています。Microsoft Graph は一意の文字列値を割り当て、それを応答内で返します。

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

{
    "id":"courses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

応答

応答には、要求の中で提供されているスキーマ名に基づいた一意の文字列がその ID プロパティ内に含まれ、新規作成したスキーマ定義の残りの部分も応答に含まれています。応答の中の ID の値は、次の形式に基づきます。ext{8-random-alphanumeric-chars}_{schema-name}。

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

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

{
    "id": "extk9eruy7c_courses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "status": "InDevelopment",
    "owner": "24d3b144-21ae-4080-943f-7067b395b913",
    "properties": [
        {
            "name": "courseId",
            "type": "String"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

例 3: 所有者を設定してスキーマ拡張機能を作成する

要求

次の例では、owner を設定してスキーマ拡張機能を作成する方法を示します。 このシナリオでは、アプリケーションのユーザーがアプリケーションの所有者でない可能性があります (たとえば、Microsoft Graph Explorer を使用している場合)。 この場合は、 owner プロパティを、所有しているアプリケーションの appId に設定する必要があります。設定しなかった場合は、スキーマ拡張の作成を承認されません。 要求の owner プロパティを設定し、schemaExtension オブジェクト内の残りのプロパティの JSON 表記を使用します。

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

{
    "id":"courses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "owner": "50897f70-a455-4adf-87bc-4cf17091d5ac",
    "properties": [
        {
            "name": "courseId",
            "type": "Integer"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

応答

応答には、要求で指定された値に設定された owner が含まれます。

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

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

{
    "id": "extk9eruy7c_courses",
    "description": "Graph Learn training courses extensions",
    "targetTypes": [
        "Group"
    ],
    "status": "InDevelopment",
    "owner": "50897f70-a455-4adf-87bc-4cf17091d5ac",
    "properties": [
        {
            "name": "courseId",
            "type": "String"
        },
        {
            "name": "courseName",
            "type": "String"
        },
        {
            "name": "courseType",
            "type": "String"
        }
    ]
}

関連項目