Excel統合ガイド

SURP MDMのマスターデータをExcelで活用する方法を説明します。Excelから直接データを取得し、レポートや分析に活用できます。

📋 概要

SURP MDMは、Excelとシームレスに統合できる専用APIを提供します。Power QueryやWeb接続機能を使って、マスターデータをExcelに直接インポートできます。

できること

  • マスターデータをExcelに直接インポート: WebAPIから最新データを取得
  • リレーションフィールドの自動展開: 参照先のデータも自動的に取得
  • Excel互換形式での表示: 日付・時刻を適切な形式で表示
  • データの自動更新: 定期的に最新データに更新
  • Power Queryでの高度なデータ変換: フィルター、結合、集計が可能
  • 複数マスターの結合: 複数のマスターを組み合わせた分析

🎯 必要なプラン

機能FreeStarterProfessionalEnterprise
基本マスター取得✅✅✅✅
Excel統合API❌❌✅✅
リレーション展開❌❌✅✅
OData接続❌❌✅✅
レート制限（分）103060無制限
レート制限（日）1001,00010,000無制限

Excel統合APIは Professional プラン以上で利用できます。

🚀 クイックスタート（5分）

ステップ1: APIキーを取得

  1. SURP MDM管理画面にログイン
  2. 設定 > APIキー を開く
  3. 「新規作成」ボタンをクリック
  4. スコープ: read（読み取り専用）を選択
  5. APIキーをコピー（例: sk_live_abc123...）

ステップ2: Excelで接続

方法1: データの取得（Web）

  1. Excel を開く

  2. 「データ」タブ → 「データの取得」 → 「その他のデータソースから」 → 「Web から」

  3. URLを入力:

    https://mdm.surp.tech/api/v1/excel/department

    ※ department の部分は、取得したいマスタータイプに変更

  4. 「詳細設定」をクリック

  5. 「HTTPリクエストヘッダーの追加」:

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

  6. 「OK」をクリック

  7. Power Query エディターが開く

  8. 「value」列を展開 → 必要な列を選択

  9. 「閉じて読み込む」をクリック

完了！部署マスターがExcelのワークシートに読み込まれました。

方法2: Power Queryスクリプト

より高度な制御が必要な場合は、Power Query（M言語）スクリプトを使用します。

  1. 「データ」タブ → 「データの取得」 → 「空のクエリ」
  2. 「詳細エディター」を開く
  3. 以下のスクリプトを貼り付け:
let
    // APIからデータ取得
    Source = Json.Document(Web.Contents(
        "https://mdm.surp.tech/api/v1/excel/department",
        [Headers=[Authorization="Bearer sk_live_あなたのAPIキー"]]
    )),

    // value配列を展開
    ValueList = Source[value],
    TableFromList = Table.FromList(ValueList, Splitter.SplitByNothing()),
    ExpandRecords = Table.ExpandRecordColumn(TableFromList, "Column1",
        {"id", "departmentCode", "departmentName", "status"}
    )
in
    ExpandRecords
  1. 「完了」→「閉じて読み込む」

📊 実践例

例1: 従業員マスターの取得

従業員データを取得し、部署名も自動展開します。

let
    // APIから従業員データを取得
    Source = Json.Document(Web.Contents(
        "https://mdm.surp.tech/api/v1/excel/employee",
        [Headers=[Authorization="Bearer sk_live_..."]]
    )),

    // value配列を展開
    ValueList = Source[value],
    TableFromList = Table.FromList(ValueList, Splitter.SplitByNothing()),
    ExpandRecords = Table.ExpandRecordColumn(TableFromList, "Column1",
        {"employeeCode", "name", "email", "department_display", "hireDate"}
    ),

    // 列名を日本語に変更
    RenameColumns = Table.RenameColumns(ExpandRecords, {
        {"employeeCode", "社員番号"},
        {"name", "氏名"},
        {"email", "メールアドレス"},
        {"department_display", "所属部署"},
        {"hireDate", "入社日"}
    }),

    // データ型を変更
    ChangeTypes = Table.TransformColumnTypes(RenameColumns, {
        {"入社日", type date}
    })
in
    ChangeTypes

結果:

社員番号氏名メールアドレス所属部署入社日
E001山田太郎[email protected]営業部2023-04-01
E002佐藤花子[email protected]人事部2022-01-15

例2: 複数マスターの結合

従業員と部署のデータを結合し、部署の詳細情報を追加します。

let
    // 従業員データ
    Employees = Json.Document(Web.Contents(
        "https://mdm.surp.tech/api/v1/excel/employee",
        [Headers=[Authorization="Bearer sk_live_..."]]
    ))[value],
    EmployeeTable = Table.FromList(Employees, Splitter.SplitByNothing()),
    ExpandEmployees = Table.ExpandRecordColumn(EmployeeTable, "Column1",
        {"employeeCode", "name", "department", "email"}
    ),

    // 部署データ
    Departments = Json.Document(Web.Contents(
        "https://mdm.surp.tech/api/v1/excel/department",
        [Headers=[Authorization="Bearer sk_live_..."]]
    ))[value],
    DepartmentTable = Table.FromList(Departments, Splitter.SplitByNothing()),
    ExpandDepartments = Table.ExpandRecordColumn(DepartmentTable, "Column1",
        {"id", "departmentCode", "departmentName", "location", "budget"}
    ),

    // 結合（department IDで）
    MergedTables = Table.NestedJoin(
        ExpandEmployees, {"department"},
        ExpandDepartments, {"id"},
        "DeptInfo",
        JoinKind.LeftOuter
    ),

    // 部署情報を展開
    ExpandDeptInfo = Table.ExpandTableColumn(MergedTables, "DeptInfo",
        {"departmentCode", "departmentName", "location", "budget"}
    )
in
    ExpandDeptInfo

例3: フィルターと並び替え

特定の条件でデータをフィルターし、並び替えます。

let
    Source = Json.Document(Web.Contents(
        "https://mdm.surp.tech/api/v1/excel/product",
        [Headers=[Authorization="Bearer sk_live_..."]]
    ))[value],
    TableFromList = Table.FromList(Source, Splitter.SplitByNothing()),
    ExpandRecords = Table.ExpandRecordColumn(TableFromList, "Column1",
        {"productCode", "productName", "price", "stock", "category"}
    ),

    // 価格が1000円以上の商品のみ
    FilterPrice = Table.SelectRows(ExpandRecords,
        each [price] >= 1000
    ),

    // 在庫が10個以上
    FilterStock = Table.SelectRows(FilterPrice,
        each [stock] >= 10
    ),

    // 価格で降順ソート
    SortByPrice = Table.Sort(FilterStock,
        {{"price", Order.Descending}}
    )
in
    SortByPrice

例4: データの自動更新設定

Excelブックを開いたときに自動的にデータを更新する設定です。

  1. Power Query エディターで接続を作成（上記の例を参照）
  2. 「閉じて読み込む」をクリック
  3. データが読み込まれた後、テーブル内を右クリック
  4. 「テーブル」→「外部データのプロパティ」
  5. 以下の設定を有効化:
    • ✅ 「ファイルを開くときにデータを更新する」
    • ✅ 「バックグラウンドで更新する」
    • 更新間隔: 60分（任意）

これで、Excelブックを開くたびに最新のマスターデータが自動的に取得されます。

🔧 Excel統合APIの詳細

エンドポイント1: 標準Excel API

GET /api/v1/excel/{master_type}

特徴:

  • リレーションフィールドを自動展開
  • 参照先のIDと表示名を両方取得
  • 日付・時刻をExcel互換形式で返却

クエリパラメータ:

パラメータ型デフォルト説明
limit整数1000最大取得件数（1〜10,000）
offset整数0スキップする件数
flatten真偽値trueリレーション展開の有無

例:

/api/v1/excel/employee?limit=500&offset=0&flatten=true

レスポンス例:

{
  "master_type": "employee",
  "total_count": 250,
  "limit": 500,
  "offset": 0,
  "has_more": false,
  "value": [
    {
      "id": "uuid-1234",
      "employeeCode": "E001",
      "name": "山田太郎",
      "department": "dept-uuid-5678",
      "department_display": "営業部",
      "hireDate": "2023-04-01"
    }
  ]
}

エンドポイント2: フラット化API

GET /api/v1/excel/{master_type}/flat

特徴:

  • すべてのデータ型をテキストまたは数値に変換
  • 配列フィールドはカンマ区切りテキスト
  • JSONフィールドは文字列化
  • Power Queryでの変換不要

例:

/api/v1/excel/product/flat?limit=1000

💡 ベストプラクティス

1. APIキーの管理

セキュリティ:

  • APIキーはExcelファイルに直接埋め込まない
  • 読み取り専用（read）スコープのみを使用
  • 定期的にAPIキーをローテーション

推奨方法:

  • 環境変数や外部ファイルにAPIキーを保存
  • または、Excelブックを保護して共有時に注意

2. パフォーマンス最適化

大量データの取得:

  • limit パラメータで分割取得（推奨: 1000件ずつ）
  • ページネーションを実装
  • 不要な列は展開しない

キャッシュの活用:

  • データの更新頻度に応じて自動更新間隔を設定
  • 静的なマスター（部署、カテゴリなど）は更新頻度を低く

3. エラーハンドリング

Power Queryでエラーをキャッチします:

let
    Source = try Json.Document(Web.Contents(
        "https://mdm.surp.tech/api/v1/excel/employee",
        [Headers=[Authorization="Bearer sk_live_..."]]
    )) otherwise null,

    Result = if Source = null then
        #table({"Message"}, {{"APIからデータを取得できませんでした"}})
    else
        Source[value]
in
    Result

⚠️ よくある質問

Q1. APIキーが認証されません

A: 以下を確認してください:

  1. APIキーの形式: Bearer sk_live_... （Bearer の後にスペースが必要）
  2. APIキーのスコープ: read スコープが付与されているか
  3. APIキーの有効性: 削除または無効化されていないか
  4. Authorizationヘッダー: 正しく設定されているか

Q2. データが取得できません（空のテーブル）

A: 以下を確認してください:

  1. マスタータイプ: URLの{master_type}が正しいか（例: employee, department）
  2. テナントID: 正しいテナントのAPIキーを使用しているか
  3. データの存在: 実際にデータが登録されているか
  4. value配列の展開: Power Queryでvalue列を正しく展開しているか

Q3. レート制限エラーが出ます

エラーメッセージ:

429 Too Many Requests

A: レート制限を超えています。

対処方法:

  • 短時間に大量のリクエストを送信しない
  • 自動更新の間隔を長くする（推奨: 60分以上）
  • プランをアップグレードしてレート制限を緩和

プラン別レート制限:

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

Q4. 日付が数値で表示されます

A: Power Queryでデータ型を変換してください:

ChangeTypes = Table.TransformColumnTypes(Source, {
    {"hireDate", type date},
    {"created_at", type datetime}
})

Q5. 参照先のデータが表示されません

A: flatten=true パラメータを使用してください:

/api/v1/excel/employee?flatten=true

これにより、department_display のような参照先の表示名が自動的に追加されます。

🔗 関連ガイド

📞 サポート

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