OData接続ガイド

SURP MDMのOData v4 APIを使用して、Excel、Power BI、Tableauなどのビジネスインテリジェンスツールからマスターデータに接続する方法を説明します。

📋 ODataとは

OData (Open Data Protocol) は、RESTful APIの標準プロトコルです。多くのBIツールやデータ分析ツールがODataをサポートしており、統一された方法でデータにアクセスできます。

ODataのメリット

自動スキーマ検出: ツールが自動的にデータ構造を認識
標準クエリ構文: $filter, $select, $orderby などの統一された構文
ページネーション: 大量データの効率的な取得
幅広い対応: Excel, Power BI, Tableau, SAP, Salesforceなど
型安全: データ型が明示的に定義される

SURP MDMのOData対応

OData バージョン: v4.0
認証方式: Bearer Token（APIキー）
エンドポイント: https://api-mdm.surp.tech/api/v1/odata

🎯 前提条件

必要なプラン

OData APIは Professional プラン以上で利用できます。

必要なもの

APIキー: read スコープ以上
対応ツール: Excel, Power BI, Tableau, その他OData v4対応ツール

🔑 APIキーの取得

SURP MDM管理画面にログイン
設定 > APIキー に移動
新しいAPIキーを作成 をクリック
以下を設定:
- 名前: OData接続用
- スコープ: read（読み取りのみ）
- 有効期限: 必要に応じて設定
生成されたAPIキーをコピー

🚀 クイックスタート

基本的な接続情報

サービスドキュメントURL

https://api-mdm.surp.tech/api/v1/odata/

⚠️ 重要: 末尾のスラッシュ / を含めてください

メタデータURL

https://api-mdm.surp.tech/api/v1/odata/$metadata

認証ヘッダー

ヘッダー名: Authorization
値: Bearer sk_live_あなたのAPIキー

📊 Excel Power Queryでの接続

Windows版Excelでの接続

方法1: ODataフィード接続（推奨）

ステップ1: ODataフィードを追加

Excel を開く
「データ」タブ → 「データの取得」 → 「その他のソースから」 → 「ODataフィード」
URLを入力:
```
https://api-mdm.surp.tech/api/v1/odata/
```
⚠️ 重要: 末尾のスラッシュ / を含めてください
「詳細設定」を選択

ステップ2: 認証設定

「HTTPリクエストヘッダーパラメーター」セクション:
- ヘッダー名: Authorization
- 値: Bearer sk_live_あなたのAPIキー
「OK」をクリック

ステップ3: エンティティ選択

Power Queryが自動的にメタデータを読み込み、エンティティ一覧を表示:

department（部署マスター）
employee（従業員マスター）
product（製品マスター）

必要なエンティティを選択
「読み込み」 または 「変換」

方法2: Power Query M言語

より高度な制御が必要な場合、M言語を使用できます。

手順

Excel を開く
「データ」タブ → 「データの取得」 → 「その他のソースから」 → 「空のクエリ」
Power Queryエディタで 「ホーム」タブ → 「詳細エディター」 をクリック
以下のコードを貼り付け:

エンティティ一覧を取得:

let
    Source = OData.Feed(
        "https://api-mdm.surp.tech/api/v1/odata",
        null,
        [
            Headers=[
                Authorization="Bearer sk_live_あなたのAPIキー"
            ],
            ODataVersion=4
        ]
    )
in
    Source

特定のエンティティを取得:

let
    Source = OData.Feed(
        "https://api-mdm.surp.tech/api/v1/odata",
        null,
        [
            Headers=[
                Authorization="Bearer sk_live_あなたのAPIキー"
            ],
            ODataVersion=4
        ]
    ),
    // エンティティ選択（例: department）
    Department = Source{[Name="department"]}[Data]
in
    Department

ODataクエリオプション付き:

let
    Source = OData.Feed(
        "https://api-mdm.surp.tech/api/v1/odata/department?" &
        "$top=100&" &
        "$orderby=created_at desc&" &
        "$select=departmentCode,departmentName,status",
        null,
        [
            Headers=[
                Authorization="Bearer sk_live_あなたのAPIキー"
            ],
            ODataVersion=4
        ]
    )
in
    Source

「sk_live_あなたのAPIキー」を実際のAPIキーに置き換え
「完了」 → 「閉じて読み込む」

Mac版Excelでの接続

Mac版ExcelでもOData接続が可能です！以下の手順に従ってください。

前提条件

Microsoft 365 Excel for Mac（バージョン 16.69以降）
Mac版の買い切り版Excelでは機能が大きく制限されます

接続手順

ステップ1: ODataフィードを追加

Excel を開く
「データ」タブ → 「データの取得」 → 「その他のソースから」 → 「ODataフィード」
URLを入力:
```
https://api-mdm.surp.tech/api/v1/odata/
```
⚠️ 重要: 末尾のスラッシュ / を含めてください
「OK」をクリック

ステップ2: 資格情報の設定

「資格情報の編集」ダイアログが表示されます：

基本認証を選択
ユーザー名: 任意の文字列（例: test）
- ⚠️ 注意: Mac版はユーザー名を空にできないため、任意の文字列を入力してください
パスワード: APIキーを入力
```
sk_live_あなたのAPIキー
```
⚠️ 注意: Bearer プレフィックスは不要です
接続をクリック

ステップ3: エンティティ選択

Power Queryが自動的にメタデータを読み込み、エンティティ一覧を表示します。必要なエンティティを選択して、「読み込み」 または 「変換」 をクリックしてください。

Excelキャッシュのクリア方法

接続エラーが発生する場合や、古いデータが表示される場合は、Excelのキャッシュをクリアしてください。

Windows

Excelを完全に閉じる
以下のフォルダを削除:
- エクスプローラーのアドレスバーに %LOCALAPPDATA%\Microsoft\Office\16.0\PowerQuery\ を入力して Enter
- フォルダ内のすべてのファイルを削除
- エクスプローラーのアドレスバーに %TEMP%\Microsoft\Power Query\ を入力して Enter
- フォルダ内のすべてのファイルを削除
Excelを再起動
新しいExcelファイルで接続を作り直す

Mac

Excelを完全に閉じる
ターミナルを開く

以下のコマンドを実行:

rm -rf ~/Library/Caches/com.microsoft.Excel/
rm -rf ~/Library/Application\ Support/Microsoft/Office/PowerQuery/

Excelを再起動
新しいExcelファイルで接続を作り直す

📈 Power BI Desktopでの接続

接続手順

ステップ1: ODataフィードを選択

Power BI Desktop を開く
「ホーム」タブ → 「データを取得」 → 「ODataフィード」
URLを入力:
```
https://api-mdm.surp.tech/api/v1/odata
```
「詳細設定」を展開

ステップ2: 認証ヘッダー設定

「HTTPリクエストヘッダー」（オプション）:
- 「新しいヘッダー」をクリック
- 名前: Authorization
- 値: Bearer sk_live_あなたのAPIキー
「OK」をクリック

ステップ3: エンティティを読み込み

ナビゲーター でエンティティを選択
「変換データ」 でクエリを編集、または 「読み込み」 で直接読み込み

Power BIでの高度な設定

リレーションシップの設定

複数のマスターを読み込んだ後、リレーションシップを設定します。

「モデル」ビューに切り替え
テーブル間をドラッグ＆ドロップで関連付け

例:

employee[department] ⇄ department[id]
product[category] ⇄ category[id]

メジャーの作成

DAX（Data Analysis Expressions）を使って集計を作成します。

従業員数 = COUNT(employee[id])
 
アクティブ従業員 =
CALCULATE(
    COUNT(employee[id]),
    employee[status] = "active"
)
 
平均年齢 = AVERAGE(employee[age])
 
部署別従業員数 =
COUNTROWS(
    RELATEDTABLE(employee)
)

自動更新の設定

「ファイル」 → 「オプションと設定」 → 「オプション」
「データ読み込み」 → 「バックグラウンドデータ」 セクション
「データの自動更新を有効にする」 をオン
更新間隔を設定（分単位、推奨: 60分）

📉 Tableauでの接続

Tableau DesktopでのOData接続

ステップ1: OData接続を選択

Tableau Desktop を開く
「接続」 → 「サーバーへ」 → 「OData」

ステップ2: サーバー情報を入力

サーバー:
```
api-mdm.surp.tech
```
パス:
```
/api/v1/odata
```
認証: 「カスタムHTTPヘッダー」 を選択

ステップ3: カスタムヘッダー設定

「ヘッダーの追加」:
- 名前: Authorization
- 値: Bearer sk_live_あなたのAPIキー
「サインイン」をクリック

ステップ4: テーブル選択

利用可能なテーブル（エンティティ）一覧が表示されます
必要なテーブルを選択してワークシートにドラッグ

🔧 ODataクエリオプション

OData v4の標準クエリオプションを使用して、サーバー側でデータを処理できます。

$filter（フィルター）

特定の条件でデータを絞り込みます。

例:

/api/v1/odata/employee?$filter=status eq 'active'
/api/v1/odata/product?$filter=price gt 1000
/api/v1/odata/department?$filter=contains(departmentName, '営業')

演算子:

eq: 等しい
ne: 等しくない
gt: より大きい
ge: 以上
lt: より小さい
le: 以下
and: AND条件
or: OR条件

$select（列選択）

必要な列のみを取得します。

例:

/api/v1/odata/employee?$select=employeeCode,name,email

$orderby（並び替え）

データを並び替えます。

例:

/api/v1/odata/employee?$orderby=hireDate desc
/api/v1/odata/product?$orderby=price asc

asc: 昇順（デフォルト）
desc: 降順

$top（件数制限）

取得する件数を制限します。

例:

/api/v1/odata/employee?$top=50

$skip（スキップ）

先頭の指定件数をスキップします（ページネーション用）。

例:

/api/v1/odata/employee?$skip=100&$top=50

→ 101〜150件目を取得

$count（件数取得）

データ件数を取得します。

例:

/api/v1/odata/employee/$count
/api/v1/odata/employee?$count=true&$top=10

複合クエリ

複数のオプションを組み合わせます。

例:

/api/v1/odata/employee?
  $filter=status eq 'active'&
  $select=employeeCode,name,department&
  $orderby=hireDate desc&
  $top=100

💡 ベストプラクティス

1. サーバーサイドフィルタリング

可能な限り $filter でサーバー側でフィルターし、ネットワーク転送量を削減します。

推奨:

/api/v1/odata/employee?$filter=status eq 'active'

非推奨:

/api/v1/odata/employee （全件取得後、クライアント側でフィルター）

2. 必要な列のみ取得

$select で必要な列のみを指定し、データ転送量を削減します。

推奨:

/api/v1/odata/employee?$select=employeeCode,name,email

非推奨:

/api/v1/odata/employee （全列取得）

3. ページネーション

大量データは $top と $skip でページネーションします。

// 1ページ目（1〜100件）
/api/v1/odata/employee?$top=100&$skip=0

// 2ページ目（101〜200件）
/api/v1/odata/employee?$top=100&$skip=100

4. APIキーの管理

読み取り専用スコープ: BIツールからの接続には read スコープのみ付与
定期的なローテーション: 3〜6ヶ月ごとにAPIキーを再作成
環境変数化: APIキーをツールに直接埋め込まない

⚠️ トラブルシューティング

Q1. メタデータを読み込めません

エラーメッセージ:

Unable to connect to the OData service

原因:

APIキーが間違っている
ネットワーク接続の問題
URLが間違っている

対処方法:

APIキーを再確認（Bearer の後にスペースが必要）
ブラウザで https://api-mdm.surp.tech/api/v1/odata/$metadata にアクセスして動作確認
URLが正しいか確認

Q2. 認証エラー（401 Unauthorized）

原因:

APIキーが無効
Authorizationヘッダーが正しく設定されていない

対処方法:

SURP MDM管理画面でAPIキーの状態を確認
ヘッダー形式を確認: Authorization: Bearer sk_live_...
APIキーに read スコープが付与されているか確認

Q3. データが表示されない

原因:

マスタータイプが間違っている
データが登録されていない
テナントIDが一致していない

対処方法:

/api/v1/odata でエンティティ一覧を確認
SURP MDM管理画面でデータが存在するか確認
正しいテナントのAPIキーを使用しているか確認

Q4. レート制限エラー（429 Too Many Requests）

原因: 短時間に大量のリクエストを送信

対処方法:

自動更新の間隔を長くする（推奨: 60分以上）
$top でページサイズを調整
プランをアップグレード

プラン別レート制限:

Free: 10リクエスト/分、100リクエスト/日
Starter: 30リクエスト/分、1,000リクエスト/日
Professional: 60リクエスト/分、10,000リクエスト/日
Enterprise: 無制限

🔗 関連ガイド

Excel統合ガイド - Excel固有の機能
Power Query統合ガイド - Power Queryの詳細
API利用ガイド - APIの基本
APIサンプルコード - プログラミング言語での実装例

📞 サポート

OData接続に関する質問は、よくある質問をご覧いただくか、システム管理者にお問い合わせください。