Microsoft Graph APIを用いてチームを作成するさまざまな方法

はじめまして!2023年に新卒入社しましたYuito Hayashiです。

現在、業務でMicrosoft Graph APIを使用しています。そこで、学んだ知識について、記事にまとめていこうと思います。


Graph APIとは

Graph APIとは、Microsoft 365のさまざまなサービスやアプリケーションを操作することのできるAPIです。今回はGraph Exploreやcurlコマンドを用いて、Microsoft Teamsのチーム作成手法について説明していこうと思います。

事前準備

アプリの登録をして、クライアントIDとクライアントシークレットの取得を行います。


  1. Microsoft Azureにログインします。

  2. Microsoft Entra IDの「アプリの登録」>「新規作成」からアプリの登録を行います。

  1. 名前、アカウントの種類、リダイレクトURIを設定して、アプリを登録してください。

  1. アプリ登録後は概要からクライアントIDを見ることができます。

  1. 「証明書とシークレット」>「新しいクライアントシークレット」からクライアントシークレットを作成することができます。

Graph Exploreを用いたチーム作成

Graph Exploreとは、Microsoft Graph APIを試すことができる開発者ツールです。

Graph Exploreを用いたチーム作成の手順を紹介します。


  1. Graph Exploreにアクセスします。ログインしていない場合は、ログインをしてください。

  2. 次に、左側の「Sample queries」から「create team」を選択してください。選択すると、チーム作成するためのHTTP requestや以下のようなRequest bodyが設定されます。

{

    "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",

    "displayName": "Architecture Team",

    "description": "The team for those in architecture design."

}


  1. 「Run query」を押すとAPIが実行されます。Request bodyを何も修正しなければ、「チーム名:Architecture Team、説明:The team for those in architecture design.」というチームが作成されます。



権限に関するエラーが出た場合は、「Modify permissions」から権限を付与することができるので、足りない権限を付与してみてください。

curlコマンドを用いたチーム作成

curlコマンドを用いたチーム作成の手順を紹介します。実行環境はPowerShellです。


  1. 以下のコマンドからアクセストークンの取得を行います。client-idはアプリ登録時のクライアントID、client-secretは作成したクライアントシークレット、tenantは自身のテナントに置き換えてください。

curl -d "client_id={client-id}" `

-d "scope=https://graph.microsoft.com/.default" `

-d "client_secret={client-secret}" `

-d "grant_type=client_credentials" `

-H "Content-Type: application/x-www-form-urlencoded" `

-X POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token


  1. コマンドを実行すると以下のような結果が返ってきます。access_tokenの値がアクセストークンとなります。

{

  "token_type":"Bearer",

  "expires_in":3600,

  "ext_expires_in":3600,

  "access_token":"eyJ0eXAiOiJKV1QiLCJub25..."

}


  1. 以下のコマンドでチームを作成することができます。access-tokenは先ほど取得したアクセストークン、user-idは自身のメールアドレスを設定してください。

curl -X POST https://graph.microsoft.com/v1.0/teams `

-H "Authorization: Bearer {access-token}" `

-H "Content-Type: application/json" `

-d "{ `

  `"template@odata.bind`": `"https://graph.microsoft.com/v1.0/teamsTemplates('standard')`", `

  `"displayName`": `"Architecture Team`", `

  `"description`":`"The team for those in architecture design.`", `

  `"members`": [ `

    { `

       `"@odata.type`": `"#microsoft.graph.aadUserConversationMember`", `

       `"roles`": [ `

           `"owner`" `

       ], `

      `"user@odata.bind`": `"https://graph.microsoft.com/v1.0/users('{user-id}')`" `

    } `

  ] `

}"


うまくいけば、「Graph Exploreを用いたチーム作成」のセクションで作成したチームと同じチームが作成されるはずです。しかし、Graph ExploreのRequest bodyと今回のコマンドではRequest bodyが異なっていることがわかります。そこで、Graph ExploreのRequest bodyと同じにした以下のコードを実行してみてください。

curl -X POST https://graph.microsoft.com/v1.0/teams `

-H "Authorization: Bearer {access-token}" `

-H "Content-Type: application/json" `

-d "{ `

  `"template@odata.bind`": `"https://graph.microsoft.com/v1.0/teamsTemplates('standard')`", `

  `"displayName`": `"Architecture Team`", `

  `"description`":`"The team for those in architecture design.`" `

}"


おそらくエラーが出てチームが作成されません。Graph Exploreでは作成されたのにcurlコマンドではうまくいかない。それはなぜでしょう?


原因は2つあります。一つは、チームにはオーナーを指定する必要があること。もう一つは、今回のcurlコマンドの実行はアプリケーションの許可によるものだからです。

Graph APIには、委任されたアクセス許可とアプリケーションの許可の2種類のアクセス許可があります。次のセクションで2種類のアクセス許可について説明します。

Graph APIのアクセス許可

Graph APIには、委任されたアクセス許可とアプリケーションの許可の2種類のアクセス許可があります。

まず、委任されたアクセス許可は、ユーザがアプリケーションにログインしている場合に使用されます。今回の場合、Graph Exploreはログインをしているので委任されたアクセス許可になります。

次に、アプリケーションの許可は、ユーザがログインしていなくてもアプリケーションを動作させるときに使用されます。先ほどのcurlコマンドはアプリケーションの許可になります。


委任されたアクセス許可の場合は、Request bodyにオーナーを指定していないと、ログインしているユーザがオーナーとなります。しかし、アプリケーションの許可の場合は、誰もログインしていないので誰をオーナーにすればいいのかわかりません。そのため、アプリケーションの許可の場合は、誰をオーナーにするか指定する必要があります。

次のセクションでは委任されたアクセス許可でcurlコマンドを用いてGraph APIを実行する手順を紹介します。

curlコマンドを用いたチーム作成(委任されたアクセス許可)

委任されたアクセス許可でcurlコマンドを用いてチームを作成する手順を紹介します。


  1. ブラウザで以下のURLにアクセスします。redirect-uriはアプリ登録時に設定したリダイレクトURI、stateには任意の値を設定してください。

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?client_id={client-id}&response_type=code&redirect_uri={redirect-uri}&response_mode=query&scope=offline_access%20Team.Create&state={state}


  1. アクセス許可の画面が表示されたら許可してください。許可すると以下のようなリダイレクトURLが返されます。stateには先ほど設定した任意の値と同じものが含まれているはずです。codeは認可コードです。

{rediret-uri}?code={code}&state={state}&session_state=1ef3e595-d…


  1. 認可コードを用いてアクセストークンを取得します。codeを先ほどの認可コードに置き換えて以下のコマンドから実行してください。

curl -X POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token `

-H "Content-Type: application/x-www-form-urlencoded" `

-d "client_id={client-id}" `

-d "scope=Team.Create" `

-d "code={code}" `

-d "redirect_uri={redirect_uri}" `

-d "grant_type=authorization_code" `

-d "client_secret={client-secret}"


  1. コマンドが実行されると以下のデータが取得されます。アクセストークンのほかにリフレッシュトークンも取得できます。

{

  "token_type":"Bearer",

  "scope", "Team.Create",

  "expires_in":3600,

  "ext_expires_in":3600,

  "access_token":"eyJ0eXAiOiJKV1QiLCJub25..."

  "refresh_token":"0.AXUAD7dHN3KxM023Db1..."

}


  1. 以下のコマンドからリフレッシュトークンを用いてアクセストークンを取得することができます。refresh-tokenは取得したリフレッシュトークンの値に置き換えてください。

curl -X POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token `

-H "Content-Type: application/x-www-form-urlencoded" `

-d "client_id={client_id}" `

-d "scope=Team.Create" `

-d "refresh_token={refresh-token}" `

-d "grant_type=refresh_token" `

-d "client_secret={client-secret}"


  1. 取得したアクセストークンを用いて以下のコマンドを実行してみてください。次は上手くいくはずです。

curl -X POST https://graph.microsoft.com/v1.0/teams `

-H "Authorization: Bearer {access-token}" `

-H "Content-Type: application/json" `

-d "{ `

  `"template@odata.bind`": `"https://graph.microsoft.com/v1.0/teamsTemplates('standard')`", `

  `"displayName`": `"Architecture Team`", `

  `"description`":`"The team for those in architecture design.`", `

}"


さいごに

今回はGraph APIをチーム作成に絞ってまとめました。しかし、Graph APIはチームの作成以外にもさまざまなことができます。ドキュメントを読んでいろいろ試してみてください!

最後まで読んでいただきありがとうございました!

(Yuito Hayashi)