動機と概要

Microsoft Graph を利用する機会があり、公式rubyライブラリ microsoftgraph/msgraph-sdk-ruby を使う上で生じた疑問をソースコードを読んでスッキリした際の備忘録。

Gemは microsoft_graph
リーディング時のコミットID e5408c4096a826ba96a802aef25ee91bf7e11894

TL;DR

Q1. なぜ？ソース内で定義されていない機能が使えるの？(例: graph.me )
- A1. メタプログラミングのテクニックを用いて metadataファイルを元に動的に定義しているから。
Q2. graph.me の他にオブジェクト経由でアクセスできる機能はどこを見ればわかるの？
- A2. metadataファイル内の NavigationProperty を見るか、:navigation_properties メソッドで確認可能。
Q3. オブジェクト経由でAPI呼び出しする際にクエリオプション($filter,$top ...等)って渡せる？
- A3. サポートされていないようなので、自前でURL生成しリクエストする処理を実装する必要あり。

Microsoft Graph は ODataプロトコルを採用

Microsoft Graphは Open Data Protocol (OData) というWebAPIのプロトコルを採用しており、
これにより、多様なクライアントでも一貫した方法でのデータアクセスに寄与しています。

公開されているリソースの形式は、APIのルートURLに $metadata を付与したURLで確認可能です。
Microsoft Graph v1.0 であれば以下がメタデータのURLになります。(XML形式)

"user"型のデータ定義を抜粋。

.xml

<EntityType Name="user" BaseType="graph.directoryObject" OpenType="true">
  <Property Name="accountEnabled" Type="Edm.Boolean"/>
  <Property Name="ageGroup" Type="Edm.String"/>
  <Property Name="assignedLicenses" Type="Collection(graph.assignedLicense)"   Nullable="false"/>
  <Property Name="assignedPlans" Type="Collection(graph.assignedPlan)"   Nullable="false"/>
  <Property Name="businessPhones" Type="Collection(Edm.String)" Nullable="false"/>
  <Property Name="city" Type="Edm.String"/>
  <Property Name="companyName" Type="Edm.String"/>
  <Property Name="consentProvidedForMinor" Type="Edm.String"/>
  <Property Name="country" Type="Edm.String"/>
  <Property Name="creationType" Type="Edm.String"/>
  <Property Name="department" Type="Edm.String"/>
  <Property Name="displayName" Type="Edm.String"/>
  <Property Name="employeeId" Type="Edm.String"/>
  <Property Name="faxNumber" Type="Edm.String"/>
  <Property Name="givenName" Type="Edm.String"/>
  ...略...
</EntityType>

OData形式については以下記事が理解の助けになりました。

参考

(本題) gem: microsoft_graph を利用する上での疑問

Microsoft Graph の公式Rubyライブラリ microsoftgraph/msgraph-sdk-ruby のREADMEより

.rb

callback = Proc.new { |r| r.headers["Authorization"] = "Bearer #{tokens.access_token}" }

graph = MicrosoftGraph.new(base_url: "https://graph.microsoft.com/v1.0",
                           cached_metadata_file: File.join(MicrosoftGraph::CACHED_METADATA_DIRECTORY, "metadata_v1.0.xml"),
                           api_version: '1.6', # Optional
                           &callback
)

me = graph.me # get the current user
puts "Hello, I am #{me.display_name}."

me.direct_reports.each do |person|
  puts "How's it going, #{person.display_name}?"
end

疑問1: `graph.me`は、直接定義されていないのになぜ動くのか？

graph.me で自身のプロフィール情報を取得できるが、
ソースコードをgrepしても MicrosoftGraphのインスタンスメソッドに me メソッドは直接的に定義されていなかった。
どのように動いているのか？ソースコードを追ってみた。

ライブラリの大元の MicrosoftGraph より

lib/microsoft_graph.rb

class MicrosoftGraph
  attr_reader :service
  BASE_URL = "https://graph.microsoft.com/v1.0/"

  def initialize(options = {}, &auth_callback)
    @service = OData::Service.new(
      api_version: options[:api_version],
      auth_callback: auth_callback,
      base_url: BASE_URL,
      metadata_file: options[:cached_metadata_file]
    )
    @association_collections = {}
    unless MicrosoftGraph::ClassBuilder.loaded?
      MicrosoftGraph::ClassBuilder.load!(service)
    end

  end

  # ... 略 ...

MicrosoftGraph::ClassBuilder.load!(service)

結論としては、このload!メソッドの処理でRubyのオブジェクト定義をしていた。

このメソッドでは、metadata(XML)のEntityType, ComplexType, EntitySet, Action, Functionタグを順にメタプログラミングのテクニックでクラス化し、
メソッドの最後に Singletonタグで定義されている内容 (me 等)を、MicrosoftGraphのインスタンスメソッドとして定義しているからgraph.me で呼び出し可能になっていた。

ClassBuilder.load! より