編集

Microsoft Graph SDK を使用して API 呼び出しを作成する

  • [アーティクル]

Microsoft Graph SDK サービス ライブラリは、すべての API リクエストを作成するための開始点として使用できるクライアント クラスを提供します。 クライアント クラスには 2 つのスタイルがあります。1 つは Fluent インターフェイスを使用してリクエスト (client.Users["user-id"].Manager など) を作成し、もう 1 つはパス文字列 (api("/users/user-id/manager")など) を受け入れます。 リクエスト オブジェクトがある場合は、フィルタリングや並べ替えなどのさまざまなオプションを指定でき、最後に、実行する操作のタイプを選択します。

クライアント クラスがまったくない Microsoft Graph PowerShell SDK もあります。 その代わりに、すべての要求は PowerShell コマンドとして表されます。 たとえば、ユーザーのマネージャーを取得するためのコマンドは Get-MgUserManager です。 API 呼び出しのコマンドを見つける方法の詳細については、「Microsoft Graph PowerShell SDK のナビゲーション」を参照してください。

Microsoft Graph から情報を読みとる

Microsoft Graph から情報を読み取るには、最初に要求オブジェクトを作成してから、要求に対して GET メソッドを実行する必要があります。

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

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

$selectを使用して、返されるプロパティを制御する

エンティティを取得するときに、すべてのプロパティが自動的に取得されるわけではありません。 明示的に選択する必要がある場合もあります。 また、一部のシナリオでは、既定値のプロパティ セットを返す必要はありません。 必要なプロパティのみを選択すると、リクエストのパフォーマンスを向上させることができます。 リクエストをカスタマイズして、プロパティのリストに $select クエリ パラメータを含めることができます。

// 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();

エンティティのリストを取得する

エンティティのリストの取得は、リクエストを構成するための他のオプションがいくつかあることを除いて、単一のエンティティの取得と似ています。 $filter クエリ パラメータを使用して、結果セットを指定された条件に一致する行のみに減らすことができます。 $orderBy クエリ パラメータは、サーバーが指定されたプロパティでソートされたエンティティのリストを提供することを要求します。

注意

リソースに対する要求Azure Active Directory、高度なクエリ機能を使用する必要があります。 クエリ パラメーターとヘッダーを$count``ConsistencyLevel含む、予期しない結果を含む、要求の不良、サポートされていないクエリ、または応答を示す応答を取得すると、要求が成功する可能性があります。 詳細と例については、「ディレクトリ オブジェクトの高度なクエリ機能Azure AD参照してください。

// 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();

エンティティのリストを取得するときに返されるオブジェクトは、ページ コレクションである可能性があります。 エンティティの完全なリストを取得する方法の詳細については、ページングによるコレクション を参照してください。

コレクションのアイテムにアクセスする

Fluent スタイルをサポートする SDK の場合、エンティティのコレクションには配列インデックスを使用してアクセスできます。 テンプレート ベースの SD Kの場合、コレクションに続くパス セグメントにアイテム識別子を埋め込むだけで十分です。 PowerShell の場合、識別子はパラメーターとして渡されます。

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

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

フィルターを $expand 使用すると、メイン エンティティを要求すると同時に、関連エンティティまたはエンティティのコレクションを要求できます。

// 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();

エントリを削除する

削除リクエストは、エンティティを取得するリクエストと同じ方法で作成されますが、GET ではなく DELETE リクエストを使用します。

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

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

POST リクエストを作成して新しいエンティティを作成する

Fluent スタイルをサポートする SDK の場合、Add メソッドを使用して新しいアイテムをコレクションに追加できます。 テンプレート ベースの SDK の場合、リクエスト オブジェクトは post メソッドを公開します。 PowerShell の場合、追加するエンティティにマッピングするパラメーターを受け入れる New-* コマンドを使用できます。 作成されたエンティティは通常、呼び出しから返されます。

// 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 を使用して既存のエンティティを更新する

Microsoft Graph のほとんどの更新は PATCH メソッドを使用して実行されるため、渡すオブジェクトに変更するプロパティを含めるだけで完了します。

// 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 ヘッダーを使用してリクエストの動作を制御する

Header() 関数を使用して、カスタムヘッダーをリクエストに添付できます。 PowerShellの場合、ヘッダーの追加は Invoke-GraphRequest メソッドでのみ可能です。 多くの Microsoft Graph シナリオでは、カスタム ヘッダーを使用してリクエストの動作を調整します。

//  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();

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

Fluent スタイルをサポートする SDK の場合、QueryOptions オブジェクトのリストを使用してカスタム クエリ パラメーター値を提供できます。 テンプレート ベースの SDK の場合、パラメーターは URL エ ンコードされ、リクエスト URL に追加されます。 PowerShell と Go の場合、特定の API の定義済みのクエリ パラメーターは、対応するコマンドのパラメーターとして公開されます。

//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();