SharePoint REST サービス エンドポイント URI を決定する

  • [アーティクル]

ヒント

始める前に、次のリソースを確認してください。

SharePoint REST サービスの概要REST サービスで表される SharePoint データ構造内を移動する

SharePoint REST エンドポイント URI の構造

REST サービスを使用して SharePoint リソースにアクセスできるようにする前に、そのリソースを指す URI エンドポイントを理解する必要があります。 これらの REST エンドポイント URI は、できる限り SharePoint クライアント オブジェクト モデルのリソースの API シグネチャ構造に近いものにされています。 例:

var items = List.GetByTitle(listname).GetItems();

ただし、場合によっては、エンドポイント URI は対応するクライアント オブジェクト モデルのシグネチャとは異なることがあります。これは REST または OData の規則に準拠するためです。

次の図に、SharePoint REST URI の一般的な構文の構造を示します。

SharePoint REST の URI 構文の構造**

SharePoint REST 要求構文

SharePoint リソースの一部のエンドポイントには、この構文の構造は適用されません。

  • 複合型のパラメーターを必要とするメソッド。 対応するクライアント オブジェクト モデルのメソッドが、渡されるパラメーターの値として複合型を要求する場合、REST の制限により、その REST エンドポイントにはこの構文の構造が適用されません。
  • 静的なメソッドとプロパティ。 静的なメソッドとプロパティを表す URI の場合、REST エンドポイントにはこの構文の構造は適用されません。

SharePoint REST サービス エンドポイントを決定する

SharePoint リソース用の REST エンドポイントを作成するには、次の手順に従います。

  1. REST サービスの参照から始めます。

    https://{site_url}/_api

  2. 適切なエントリ ポイントを指定します。 例:

    https://{site_url}/_api/web

  3. エントリ ポイントから、アクセスする特定のリソースに移動します。 これには、クライアント オブジェクト モデルのメソッドに対応するエンドポイントのパラメーターの指定が含まれます。 以下に例を示します。

    https://{site_url}/_api/web/lists/getbytitle('{list_name}')

エンドポイント URI で SharePoint REST サービスを参照する

エンドポイント URI で SharePoint REST サービスであることを示すには、_api を使用します。 REST サービスは client.svc Web サービスの一部です。 しかし、REST URI を簡単に作成し、基になる REST URI パスを短くするために、REST サービスでは _api を使用して、client.svc Web サービスを明示的に参照する手間を省いています。

このようにしても、REST サービスは、client.svc Web サービスを参照する URI を識別し受け入れます。 たとえば、https://{site_url}/_api/web/lists とせずに、https://{site_url}/_vti_bin/client.svc/web/lists と指定することもできます。 ただし、_api を使用することをお勧めします。 URL には 256 文字の制限があるため、_api を使用してベース URI の長さを短くすることで、URL の他の部分に使う文字の数を増やすことができます。

SharePoint REST サービスのエントリ ポイントを指定する

REST サービスの主なエントリ ポイントは、指定されたコンテキストのサイト コレクションとサイトを表します。 この方法で、これらのエントリ ポイントはクライアント オブジェクト モデルの ClientContext.Site プロパティおよび ClientContext.Web プロパティに対応します。

特定のサイト コレクションにアクセスするには、次の構造を使用します。

https://{site_url}/_api/site

特定のサイトにアクセスするには、次の構造を使用します。

https://{site_url}/_api/web

/site と /web に加え、REST サービスには、他のアクセス ポイントがいくつか用意されており、開発者はそれらを使って特定の機能にアクセスすることができます。 次の表は、これらのアクセス ポイントの一部を示しています。

機能領域 アクセス ポイント
サイト https://{site_url}/_api/site
Web https://{site_url}/_api/web
ユーザー プロファイル https://{site_url}/_api/SP.UserProfiles.PeopleManager
検索 https://{site_url}/_api/search

ここから、スラッシュ (/) で区切ったクライアント オブジェクト モデルの API 名を使用して、オブジェクト モデルを "階層化" することで、さらに具体的な REST エンドポイントを作成します。 次の表は、クライアント オブジェクト モデルの呼び出しと同値の REST エンドポイントの例を示しています。

クライアント オブジェクト モデル API REST エンドポイント
ClientContext.Web.Lists https://{site_url}/_api/web/lists
ClientContext.Web.Lists[guid] https://{site_url}/_api/web/lists('<guid>')
ClientContext.Web.Lists.GetByTitle("Title") https://{site_url}/_api/web/lists/getbytitle('<Title>')

エンドポイント URL では大文字と小文字が区別されます。 たとえば前述の表で、/getbytitle を使用して GetByTitle() メソッドに相当する REST を指定します。

REST エンドポイント URI でのパラメーターを指定する

SharePoint では OData 仕様が拡張されており、かっこ () を使用してメソッドのパラメーターとインデックスの値を指定することができます。 これにより、同名の複数のパラメーターを含む URI における曖昧性の問題を回避できます。 たとえば、次の 2 つの URI には、同じ名前のパラメーターが含まれています。

https://{site_url}/_api/web/lists/getByTitle('Announcements')/fields/getByTitle('Description')

https://{site_url}/_api/web/lists('{list_guid}')/fields/getById('{guid}')

複数のパラメーターを指定するには、名前と値をペアにしたパラメーターを指定し、各パラメーターをコンマで区切ります。 例:

https://{site_url}/_api/web/getAvailableWebTemplates(lcid=1033, includeCrossLanguage=true)

次の図は、SharePoint の REST パラメーターの構文を示しています。

SharePoint の REST パラメーターの構文

SharePoint REST サービス メソッド パラメーターの構文

REST サービスのパラメーターとしての複合型

クライアント オブジェクト モデルの一部のメソッドでは、大きな負荷のかかるパラメーターを必要とするものがあります。 REST エンドポイントでは、相当するクライアント オブジェクト モデル API との機能の同等性を維持するために、複合型のパラメーターを受け入れる必要があります。 このような場合、REST サービスは既存の OData プロトコルを拡張し、これらの REST エンドポイントが複合型のパラメーターを 1 つ受け入れるようにします。 これは POST 操作のみに適用され、複合型は OData 標準に従って、 Atom 形式または JSON 形式で渡す必要があります。

たとえば、ListCollection.Add メソッドはパラメーターに Microsoft.SharePoint.Client.ListCreationInformation オブジェクトをとります。 特定のサイトにリストを追加するには、まず次のような適切な REST エンドポイントを作成します。

POST https://{site_url}/_api/web/lists/add
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}

{ "d" : {
    "results": {
      "__metadata": {
        "type": "SP.ListCreationInformation"
      },
      "CustomSchemaXml": "…large payload…/",
      "Description": "desc",
      "DocumentTemplateType": "1",
      "TemplateType": "101",
      "Title": "Announcements"
    }
  }
}

REST サービスの呼び出しにパラメーター エイリアスを使用する

OData の "パラメーター エイリアシング" セマンテックを使用して SharePoint REST エンドポイントにパラメーターを渡すことができます。 パラメーター エイリアシングでは、パラメーター値は、パラメーター呼び出し内のエイリアスで識別され、実際の値は、URI のクエリ文字列で指定します。 これにより、使用できる文字の種類を増やすことができ、クエリ文字列を使用して、一貫性のある形式を維持できます。

たとえば、次の 2 つの REST URI が同等です。

パラメーターの値を直接指定します。

https://{site_url}/_api/web/applyWebTemplate("STS#0")

パラメーター エイリアスを使用し、URI のクエリ文字列に実際のパラメーター値を指定します。

https://{site_url}/_api/web/applyWebTemplate(title=@template)?@template="STS#0"

ただし、SharePoint REST サービスでは、パラメーター エイリアシングで複合型を渡すことはできません。 たとえば、パラメーター エイリアスに複合型を含んだ次の URI はサポートされません。

https://{site_url}/_api/userProfiles/People(7)/GetWorkplace(@address)?@address={"__metadata":{"type: "ODataDemo.Address"},"Street":"NE 228th", "City":"Sammamish","State":"WA","ZipCode":"98074","Country": "USA"}

SharePoint REST サービスのパラメーター エイリアシングの構文

SharePoint REST サービスのパラメーター エイリアシングの構文

パラメーター値にディクショナリを指定する

Dictionary<String, String> ディクショナリをパラメーターにとるメソッドに対応する REST エンドポイントの場合、クエリ文字列内に、名前と値のペアをコンマで区切ったパラメーターとしてディクショナリを渡します。

REST サービスのディクショナリ パラメーターの構文

REST サービスのディクショナリ パラメーターの構文

Dictionary<String, object> は、以下の文字列プロパティを含む、KeyedPropertyValue という名前の複数値オブジェクトとして表されます。

  • Key: 複数値オブジェクトのキー。
  • Value: オブジェクトの値。
  • ValueType オブジェクトの値の型。 既存のエンティティ データ モデル (EDM) 型にマップされる単純な値型の場合、REST サービスは適切な EDM 型文字列を返します。たとえば、"Edm.String" です。そうでない場合、REST サービスは Type.ToString 関数によって返される値型を返します。

クエリ文字列にパラメーター値を指定する

REST URI がメソッド呼び出しで終了する場合は、クエリ文字列構文を使用して、メソッドのパラメーター値を指定できます。 以下に例を示します。

https://{site_url}/_api/web/applyWebTemplate?template="STS#0"

次の図は、クエリ文字列の REST サービスのパラメーターの構文を示しています。

クエリ文字列の REST サービスのパラメーターの構文

クエリ文字列の REST サービスのパラメーターの構文

静的メソッドとプロパティを REST サービス URI として指定する

静的メソッドとプロパティに対応する URI を作成するには、ECMAScript オブジェクト モデルの対応する API 名 (名前空間の宣言から開始し、ドット表記を使用) を使用します。 たとえば、 SP です。ECMAScript クライアント オブジェクト モデルの Utilities.Utility.getImageUrl(imageName) には、次の REST と同等のものがあります。

https://{site_url}/_api/SP.Utilities.Utility.getImageUrl('imageName')

ただし、静的プロパティは直接にしかアクセスできず、長い URI 構造の一部にすることはできません。 たとえば、次のように、REST の SP.Utility.AssetsLibrary メソッドに直接アクセスすることができます。

https://{site_url}/_api/SP.Utility.assetsLibrary/id

一方、次の例のように複雑な URI の場合、このリソース ロケーションをパラメーターとして使用することはできません。

https://{site_url}/_api/getList(~SP.Utility/assetsLibrary/id)

次の図は、SharePoint REST サービスの静的メンバーの構文を示しています。

SharePoint REST サービスの静的メンバーの構文

クエリ文字列の REST サービスのパラメーターの構文

エンドポイントから要求したデータを選択、フィルター処理、または並べ替える場合、SharePoint REST サービスは 広範な OData クエリ文字列操作をサポートします。 詳細については、「SharePoint REST 要求で OData クエリ操作を使用する」を参照してください。

関連項目