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

最終更新日：2023年12月20日

技術

コピーしました

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

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

Graph APIとは

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

事前準備

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

Microsoft Azureにログインします。
Microsoft Entra IDの「アプリの登録」>「新規作成」からアプリの登録を行います。

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

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

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

Graph Exploreを用いたチーム作成

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

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

Graph Exploreにアクセスします。ログインしていない場合は、ログインをしてください。
次に、左側の「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."    
}

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

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

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

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

以下のコマンドからアクセストークンの取得を行います。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

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

{
    "token_type":"Bearer",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJ0eXAiOiJKV1QiLCJub25..."
}

以下のコマンドでチームを作成することができます。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コマンドを用いてチームを作成する手順を紹介します。

ブラウザで以下の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}

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

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

認可コードを用いてアクセストークンを取得します。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}"

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

{
    "token_type":"Bearer",   
    "scope":"Team.Create",
    "expires_in":3600,
    "ext_expires_in":3600,
    "access_token":"eyJ0eXAiOiJKV1QiLCJub25...",
    "refresh_token":"0.AXUAD7dHN3KxM023Db1..."
}

以下のコマンドからリフレッシュトークンを用いてアクセストークンを取得することができます。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}"

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

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)

Gluegent Blog