Microsoft Graph Sdk を使用して API 呼び出しを行うMake API calls using the Microsoft Graph SDKs

Microsoft Graph SDK サービスライブラリは、すべての API 要求を作成するための開始点として使用できるクライアントクラスを提供します。The Microsoft Graph SDK service libraries provide a client class that you can use as the starting point for creating all API requests. クライアントクラスには、次の2つのスタイルがあります。1つは fluent インターフェイスを使用して要求を作成し、もう1つは client.Users["user-id"].Manager パス文字列を受け入れます (たとえば、 api("/users/user-id/manager") )。There are two styles of client class: one uses a fluent interface to create the request (for example, client.Users["user-id"].Manager) and the other accepts a path string (for example, api("/users/user-id/manager")). 要求オブジェクトがある場合は、フィルター処理や並べ替えなどのさまざまなオプションを指定できます。最後に、実行する操作の種類を選択できます。When you have a request object, you can specify a variety of options such as filtering and sorting, and finally, you select the type of operation you want to perform.

また、クライアントクラスをまったく持たない Microsoft Graph POWERSHELL SDKもあります。There is also the Microsoft Graph PowerShell SDK, which has no client class at all. 代わりに、すべての要求が PowerShell コマンドとして表されます。Instead, all requests are represented as PowerShell commands. たとえば、ユーザーの上司を取得するには、次のコマンドを実行し Get-MgUserManager ます。For example, to get a user's manager, the command is Get-MgUserManager. API 呼び出しのコマンドの検索の詳細については、「 Microsoft Graph POWERSHELL SDK のナビゲート」を参照してください。For more information on finding commands for API calls, see Navigating the Microsoft Graph PowerShell SDK.

Microsoft Graph から情報を読み取るRead information from Microsoft Graph

Microsoft Graph から情報を読み取るには、最初に要求オブジェクトを作成し、次に、要求に対してメソッドを実行する必要があり GET ます。To read information from Microsoft Graph, you first need to create a request object and then run the GET method on the request.

// GET https://graph.microsoft.com/v1.0/me

var user = await graphClient.Me
    .Request()
    .GetAsync();

$select を使用して返されるプロパティを制御するUse $select to control the properties returned

エンティティを取得するときに、すべてのプロパティが自動的に取得されるわけではありません。場合によっては、明示的に選択する必要があります。When retrieving an entity, not all properties are automatically retrieved; sometimes they need to be explicitly selected. また、一部のシナリオでは、既定のプロパティセットを返す必要はありません。Also, in some scenarios it isn't necessary to return the default set of properties. 必要なプロパティのみを選択すると、要求のパフォーマンスが向上します。Selecting just the required properties can improve the performance of the request. 要求をカスタマイズして、プロパティのリストを使用してクエリパラメーターを含めることができ $select ます。You can customize the request to include the $select query parameter with a list of properties.

// GET https://graph.microsoft.com/v1.0/me?$select=displayName,jobTitle

var user = await graphClient.Me
    .Request()
    .Select(u => new {
        u.DisplayName,
        u.JobTitle
    })
    .GetAsync();

エンティティの一覧を取得するRetrieve a list of entities

エンティティの一覧の取得は、1つのエンティティを取得するのと似ていますが、要求を構成するための他の多くのオプションがあります。Retrieving a list of entities is similar to retrieving a single entity except there a number of other options for configuring the request. クエリパラメーターを使用すると、指定された $filter 条件に一致する行だけに結果セットを減らすことができます。The $filter query parameter can be used to reduce the result set to only those rows that match the provided condition. $orderByクエリパラメーターは、指定されたプロパティによって並べ替えられたエンティティのリストをサーバーに提供するように要求します。The $orderBy query parameter will request that the server provide the list of entities sorted by the specified properties.

// GET https://graph.microsoft.com/v1.0/me/messages?$select=subject,sender&$filter=<some condition>&orderBy=receivedDateTime

var messages = await graphClient.Me.Messages
    .Request()
    .Select(m => new {
        m.Subject,
        m.Sender
    })
    .Filter("<filter condition>")
    .OrderBy("receivedDateTime")
    .GetAsync();

エンティティのリストを取得するときに返されるオブジェクトは、ページングされたコレクションである可能性があります。The object returned when retrieving a list of entities is likely to be a paged collection. エンティティの完全なリストを取得する方法の詳細については、「 コレクションのページング」を参照してください。For details about how to get the complete list of entities, see paging through a collection.

コレクションのアイテムにアクセスするAccess an item of a collection

Fluent スタイルをサポートする Sdk では、エンティティのコレクションに配列インデックスを使用してアクセスできます。For SDKs that support a fluent style, collections of entities can be accessed using an array index. テンプレートベースの Sdk の場合は、コレクションの後のパスセグメントにアイテム識別子を埋め込むだけで十分です。For template-based SDKs, it is sufficient to embed the item identifier in the path segment following the collection. PowerShell の場合、識別子はパラメーターとして渡されます。For PowerShell, identifiers are passed as parameters.

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}

string messageId = "AQMkAGUy..";
var message = await graphClient.Me.Messages[messageId]
    .Request()
    .GetAsync();

フィルターを使用して、 $expand メインエンティティを要求するのと同じ方法で、関連するエンティティまたはエンティティのコレクションを要求できます。You can use the $expand filter to request a related entity, or collection of entities, at the same that you request the main entity.

// GET https://graph.microsoft.com/v1.0/me/messages/{message-id}?$expand=attachments

string messageId = "AQMkAGUy...";
var message = await graphClient.Me.Messages[messageId]
    .Request()
    .Expand("attachments")
    .GetAsync();

エンティティを削除するDelete an entity

Delete 要求は、エンティティを取得する要求と同じ方法で作成されますが、で DELETE はなく要求を使用し GET ます。Delete requests are constructed in the same way as requests to retrieve an entity, but use a DELETE request instead of a GET.

// DELETE https://graph.microsoft.com/v1.0/me/messages/{message-id}

string messageId = "AQMkAGUy...";
var message = await graphClient.Me.Messages[messageId]
    .Request()
    .DeleteAsync();

POST 要求を作成して新しいエンティティを作成するMake a POST request to create a new entity

Fluent スタイルをサポートする Sdk では、新しいアイテムをメソッドを使用してコレクションに追加でき Add ます。For SDKs that support a fluent style, new items can be added to collections with an Add method. テンプレートベースの Sdk の場合、要求オブジェクトはメソッドを公開し post ます。For template-based SDKs, the request object exposes a post method. PowerShell の場合、 New-* 追加するエンティティにマップされたパラメーターを受け付けるコマンドが使用可能です。For PowerShell, a New-* command is available that accepts parameters that map to the entity to add. 通常、作成されたエンティティは呼び出しから返されます。The created entity is usually returned from the call.

// POST https://graph.microsoft.com/v1.0/me/calendars

var calendar = new Calendar
{
    Name = "Volunteer"
};

var newCalendar = await graphClient.Me.Calendars
    .Request()
    .AddAsync(calendar);

PATCH を使用して既存のエンティティを更新するUpdating an existing entity with PATCH

Microsoft Graph の更新プログラムのほとんどは、メソッドを使用して実行されるので、 PATCH 渡されるオブジェクトで変更するプロパティのみを含める必要があります。Most updates in Microsoft Graph are performed using a PATCH method and therefore it is only necessary to include the properties that you want to change in the object you pass.

// PATCH https://graph.microsoft.com/v1.0/teams/{team-id}

var team = new Team
{
    FunSettings = new TeamFunSettings
    {
        AllowGiphy = true,
        GiphyContentRating = GiphyRatingType.Strict
    }
};

var teamId = "71766077-aacc-470a-be5e-ba47db3b2e88";

await graphClient.Teams[teamId]
    .Request()
    .UpdateAsync(team);

HTTP ヘッダーを使用して要求の動作を制御するUse HTTP headers to control request behavior

関数を使用して、 Header() 要求にカスタムヘッダーを付加することができます。You can use a Header() function to attach custom headers to a request. PowerShell では、ヘッダーの追加はメソッドでのみ可能です Invoke-GraphRequestFor PowerShell, adding headers is only possible with the Invoke-GraphRequest method. Microsoft Graph のさまざまなシナリオでは、カスタムヘッダーを使用して要求の動作を調整します。A number of Microsoft Graph scenarios use custom headers to adjust the behavior of the request.

//  GET https://graph.microsoft.com/v1.0/users/{user-id}/events

var events = await graphClient.Me.Events
    .Request()
    .Header("Prefer",@"outlook.timezone=""Pacific Standard Time""")
    .Select( e => new {
        e.Subject,
        e.Body,
        e.BodyPreview
    })
    .GetAsync();

カスタムクエリパラメーターを提供するProvide custom query parameters

Fluent スタイルをサポートする Sdk では、オブジェクトのリストを使用してカスタムクエリパラメーター値を提供でき QueryOptions ます。For SDKs that support a fluent style, you can provide custom query parameter values by using a list of QueryOptions objects. テンプレートベースの Sdk の場合、パラメーターは URL エンコードされ、要求 URI に追加されます。For template-based SDKs, the parameters are URL-encoded and added to the request URI. PowerShell の場合、指定した API の定義されたクエリパラメーターは、対応するコマンドのパラメーターとして公開されます。For PowerShell, defined query parameters for a given API are exposed as parameters to the corresponding command.

//GET https://graph.microsoft.com/v1.0/me/calendarView

var queryOptions = new List<QueryOption>()
{
    new QueryOption("startdate", "2020-12-01T00:00:00Z"),
    new QueryOption("enddate", "2020-12-30T00:00:00Z")
};

var calendar = await graphClient.Me.CalendarView()
    .Request(queryOptions)
    .GetAsync();