fileset-api

Domo FileSets — App Framework API

ステータス： この API はベータ版であり、変更される可能性があります。防御的に実装し、呼び出しを try/catch で囲み、ユーザーにわかりやすいエラーを表示してください。

FileSets は Domo のファイルストレージシステムです。カスタムアプリからファイルのアップロードとダウンロード、ディレクトリツリーの参照、名前による検索、ファイルの内容に対する AI を活用したセマンティッククエリの実行ができます。

セットアップ — manifest の設定は不要です

データセットとは異なり、fileset には manifest.json のエントリーは必要ありません。サービスファイルで fileset ID を定数として定義するだけです。

// src/services/api.js
const FILESET_ID = 'b6ebf7e9-64ae-4e6d-b8ca-b356fe62923f'; // replace with your fileset ID

fileset ID は Domo の UI、または fileset-cli スキル（filesets search --name "..."）で取得できます。

---

URL パターン：/api/ と /domo/

Domo カスタムアプリ内では、次の 2 つの方法を使用できます。

パターン	使用する場面
fetch('/api/files/v1/...')	最もシンプルです。すべての JSON 呼び出しとバイナリ呼び出しに使用します。インポートは不要です。
domo.get('/domo/files/v1/...')	domo.js プロキシを使いたい場合（例：すでにほかの場所で domo.* を使用している場合）に使用します。JSON のみで、バイナリは扱えません。

以下の例では fetch('/api/...') を使用しています。JSON とバイナリ（アップロード／ダウンロード）の両方を一貫して扱えるためです。バイナリ操作では、いずれの場合も fetch を使用する必要があります。

---

ファイル

fileset 内のファイルを一覧表示する

const response = await fetch(`/api/files/v1/filesets/${FILESET_ID}/files/search`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    fieldSort: [{ field: 'created', order: 'DESC' }],
    filters: [],
    dateFilters: []
  })
});
const data = await response.json();
const files = data.files; // array of file objects

ディレクトリと名前で絞り込む場合：

const response = await fetch(
  `/api/files/v1/filesets/${FILESET_ID}/files/search` +
  `?directoryPath=/reports&immediateChildren=true&limit=50`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      fieldSort: [{ field: 'name', order: 'ASC' }],
      filters: [{ field: 'name', value: ['.pdf'], operator: 'LIKE' }],
      dateFilters: []
    })
  }
);

ページネーションには、data.pageContext.next の next トークンを使用します。

// data.pageContext shape: { next, offset, limit, total }
if (data.pageContext.next) {
  const nextPage = await fetch(
    `/api/files/v1/filesets/${FILESET_ID}/files/search?next=${data.pageContext.next}`,
    { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({}) }
  );
}

ファイルのメタデータを取得する

// By file ID
const response = await fetch(`/api/files/v1/filesets/${FILESET_ID}/files/${fileId}`);
const file = await response.json();
// { id, path, name, fileType, contentType, size, hash, created, createdBy }

// By path (when you know the directory structure)
const response = await fetch(
  `/api/files/v1/filesets/${FILESET_ID}/path?path=${encodeURIComponent('/reports/march.pdf')}`
);

ファイルをダウンロードする

fetch を使用し、一時的なダウンロードリンクを作成します。ダウンロードエンドポイントはバイナリコンテンツを返します。

async function downloadFile(fileId, filename) {
  const response = await fetch(
    `/api/files/v1/filesets/${FILESET_ID}/files/${fileId}/download`
  );
  if (!response.ok) throw new Error(`Download failed: ${response.status}`);

  const blob = await response.blob();
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = filename;
  a.click();
  URL.revokeObjectURL(url);
}

テキストベースのファイルの場合は、.blob() の代わりに .text() を使用して、コンテンツを直接読み取ることもできます。

const response = await fetch(`/api/files/v1/filesets/${FILESET_ID}/files/${fileId}/download`);
const text = await response.text(); // use for .txt, .csv, .md, etc.

ファイルをアップロードする

2 つのパート（バイナリファイルとディレクトリのメタデータ）を含む FormData を使用します。Content-Type は設定しないでください。ブラウザーが適切な multipart boundary を自動的に設定します。

async function uploadFile(file, directoryPath = '/') {
  const formData = new FormData();
  formData.append('file', file);                                           // File or Blob
  formData.append('createFileRequest', JSON.stringify({ directoryPath })); // metadata

  const response = await fetch(`/api/files/v1/filesets/${FILESET_ID}/files`, {
    method: 'POST',
    body: formData
    // ⚠️ Do NOT set Content-Type header — browser handles it
  });

  if (!response.ok) throw new Error(`Upload failed: ${response.status}`);
  return response.json(); // returns the new file object
}

ファイル入力要素からアップロードする場合：

document.getElementById('file-input').addEventListener('change', async (e) => {
  const file = e.target.files[0];
  const record = await uploadFile(file, '/uploads/2024');
  console.log('Uploaded:', record.id, record.path);
});

生成した Blob（CSV のエクスポートなど）からアップロードする場合：

const csv = 'name,value\nAlice,100\nBob,200';
const blob = new Blob([csv], { type: 'text/csv' });
const file = new File([blob], 'export.csv', { type: 'text/csv' });
await uploadFile(file, '/exports');

ファイルを削除する

// By file ID
await fetch(`/api/files/v1/filesets/${FILESET_ID}/files/${fileId}`, { method: 'DELETE' });

// By path
await fetch(
  `/api/files/v1/filesets/${FILESET_ID}/path?path=${encodeURIComponent('/reports/march.pdf')}`,
  { method: 'DELETE' }
);

---

FileSets（コンテナー）

通常は fileset がすでに存在し、アプリではハードコードした ID を使用するだけですが、アプリ内から fileset コンテナーを作成および管理することもできます。

fileset を検索する

const response = await fetch('/api/files/v1/filesets/search?limit=50', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    fieldSort: [{ field: 'updated', order: 'DESC' }],
    filters: [{ field: 'name', value: ['reports'], operator: 'LIKE' }],
    dateFilters: []
  })
});

fileset を作成する

const response = await fetch('/api/files/v1/filesets', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Monthly Reports', description: 'Automated PDF outputs' })
});
const fileset = await response.json();
const filesetId = fileset.id;

---

AI を活用したファイルクエリ

fileset で aiEnabled: true が必要です。ファイルの内容に対して自然言語の質問を実行し、関連性スコア付きでランク付けされた一致結果を返します。

const response = await fetch(`/api/files/v1/filesets/${FILESET_ID}/query`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: 'What were the key revenue drivers last quarter?',
    directoryPath: '/reports/2024',
    topK: 5
  })
});
const data = await response.json();
// data.matches: [{ id, node: { file object }, score: 0.89 }, ...]

---

ファイルオブジェクトの構造

{
  "id": "xyz789-file-id",
  "path": "/reports/2024/march.pdf",
  "name": "march.pdf",
  "fileType": "PDF",
  "contentType": "application/pdf",
  "size": 204800,
  "hash": "sha256:abc...",
  "hashAlgorithm": "SHA256",
  "created": "2024-03-01T08:00:00Z",
  "createdBy": 12345
}

---

完全な例：ファイルブラウザーのサービス

React アプリ向けのシンプルなサービスモジュールのパターンです。

// src/services/filesetApi.js

const FILESET_ID = 'your-fileset-id-here';
const BASE = `/api/files/v1/filesets/${FILESET_ID}`;

export async function listFiles(directoryPath = null, nameFilter = null) {
  const params = new URLSearchParams({ limit: '100' });
  if (directoryPath) params.set('directoryPath', directoryPath);

  const filters = nameFilter
    ? [{ field: 'name', value: [nameFilter], operator: 'LIKE' }]
    : [];

  const response = await fetch(`${BASE}/files/search?${params}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ fieldSort: [{ field: 'name', order: 'ASC' }], filters, dateFilters: [] })
  });
  if (!response.ok) throw new Error(`List failed: ${response.status}`);
  const data = await response.json();
  return data.files ?? [];
}

export async function downloadFileContent(fileId) {
  const response = await fetch(`${BASE}/files/${fileId}/download`);
  if (!response.ok) throw new Error(`Download failed: ${response.status}`);
  return response.text(); // swap for .blob() for binary files
}

export async function uploadFile(file, directoryPath = '/') {
  const form = new FormData();
  form.append('file', file);
  form.append('createFileRequest', JSON.stringify({ directoryPath }));
  const response = await fetch(`${BASE}/files`, { method: 'POST', body: form });
  if (!response.ok) throw new Error(`Upload failed: ${response.status}`);
  return response.json();
}

export async function queryFiles(question, directoryPath = null, topK = 5) {
  const body = { query: question, topK };
  if (directoryPath) body.directoryPath = directoryPath;
  const response = await fetch(`${BASE}/query`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  if (!response.ok) throw new Error(`Query failed: ${response.status}`);
  const data = await response.json();
  return data.matches ?? [];
}

---

CLI から fileset を管理する

fileset ID の確認、ファイルの参照、ディスクへのダウンロード、またはアプリ外でのコマンド実行には、fileset-cli スキルを使用してください。