メインコンテンツまでスキップ

デザインパラメータ取得

GET /file/design/parameter/{designId} エンドポイントは、指定されたデザインIDのパラメータ構造を取得します。PDFやサムネイル生成時に必要なパラメータのスキーマを確認できます。

エンドポイント情報​

  • URL: https://api.re-port-flow.com/v1/file/design/parameter/{designId}
  • メソッド: GET
  • 認証: appkey ヘッダーが必要

使用例​

cURL​

# 最新バージョンのパラメータを取得
curl -X GET https://api.re-port-flow.com/v1/file/design/parameter/550e8400-e29b-41d4-a716-446655440000 \
  -H "appkey: your-application-key"

# 特定バージョンのパラメータを取得
curl -X GET "https://api.re-port-flow.com/v1/file/design/parameter/550e8400-e29b-41d4-a716-446655440000?version=1" \
  -H "appkey: your-application-key"

JavaScript​

async function getDesignParameters(designId, version = null) {
  const baseUrl = 'https://api.re-port-flow.com/v1';
  const url = version
    ? `${baseUrl}/file/design/parameter/${designId}?version=${version}`
    : `${baseUrl}/file/design/parameter/${designId}`;

  const response = await axios.get(url, {
    headers: {
      'appkey': process.env.APP_KEY
    }
  });

  return response.data;
}

// 使用例
const schema = await getDesignParameters('550e8400-...');
console.log('パラメータスキーマ:', schema);

Python​

def get_design_parameters(design_id, version=None):
    base_url = "https://api.re-port-flow.com/v1"
    url = f"{base_url}/file/design/parameter/{design_id}"

    if version:
        url += f"?version={version}"

    headers = {
        'appkey': os.getenv('APP_KEY')
    }

    response = requests.get(url, headers=headers)
    response.raise_for_status()

    return response.json()

# 使用例
schema = get_design_parameters('550e8400-...')
print('パラメータスキーマ:', schema)

パラメータ​

パラメータ型必須説明
designIdstring (UUID)✓デザインID（パスパラメータ）
versioninteger-バージョン番号（クエリパラメータ、省略時は最新）

レスポンス​

成功時 (200 OK)​

[
  { "name": "customerName", "type": "text", "label": "顧客名" },
  { "name": "invoiceNumber", "type": "text", "label": "請求書番号" },
  { "name": "amount", "type": "number", "label": "金額" },
  {
    "name": "items",
    "type": "array",
    "label": "明細",
    "spec": [
      { "name": "name", "type": "text", "label": "品目" },
      { "name": "price", "type": "number", "label": "単価" },
      { "name": "quantity", "type": "number", "label": "数量" }
    ]
  },
  { "name": "issueDate", "type": "date", "label": "発行日" }
]

レスポンスは、入力画面を構築できるパラメータ定義の配列です。name はPDF生成時の params のキー、label は表示名です。description は設定されている場合のみ含まれ、array と collection は子フィールドを spec に持ちます。

type の値:

型説明例
text文字列（デザイン側の string / url）"山田太郎"
number数値1000
date日付（ISO 8601）"2024-02-12"
boolean真偽値true
collectionspec で定義されたネストオブジェクト{ "name": "値" }
arrayspec で行構造が定義された配列[{ "item": 1 }]

エラー時​

404 Not Found​

{
  "statusCode": 404,
  "message": "指定したデザインが存在しません",
  "error": "Not Found"
}

原因: 指定されたデザインIDまたはバージョンが存在しない（特定バージョンが見つからない場合は 指定したバージョン（X）が存在しません が返ります）

ユースケース​

動的フォーム生成​

デザインパラメータから入力フォームを動的に生成する例。

function createFieldElement(field, path = field.name) {
  if (['text', 'number', 'date', 'boolean'].includes(field.type)) {
    const input = document.createElement('input');
    input.type = field.type === 'boolean' ? 'checkbox' : field.type;
    input.name = path;
    input.setAttribute('aria-label', field.label);

    if (field.type === 'text' || field.type === 'number') {
      input.placeholder = field.label;
    }

    return input;
  }

  if (field.type === 'array' || field.type === 'collection') {
    const fieldset = document.createElement('fieldset');
    const legend = document.createElement('legend');
    legend.textContent = field.label;
    fieldset.append(legend);

    // 配列は最初の行を生成。必要に応じて同じ方法で行を追加する。
    const childPath = field.type === 'array' ? `${path}[0]` : path;
    for (const child of field.spec ?? []) {
      fieldset.append(
        createFieldElement(child, `${childPath}.${child.name}`),
      );
    }

    return fieldset;
  }

  return document.createDocumentFragment();
}

async function createDynamicForm(designId) {
  // パラメータスキーマを取得
  const schema = await getDesignParameters(designId);

  // API由来の値をHTML文字列へ埋め込まず、DOM APIで安全にフィールドを生成
  const form = document.createElement('form');

  for (const field of schema) {
    form.append(createFieldElement(field));
  }

  return form;
}

name や label はDOMプロパティとして設定するため、HTMLマークアップとして解釈されません。

バリデーション​

function validateObject(params, schema, path, errors) {
  for (const field of schema) {
    if (!Object.prototype.hasOwnProperty.call(params, field.name)) {
      // このAPIは必須属性を返さないため、未指定フィールドは検証対象外
      continue;
    }

    const value = params[field.name];
    const fieldPath = path ? `${path}.${field.name}` : field.name;

    if (field.type === 'text' && typeof value !== 'string') {
      errors.push(`${fieldPath} は文字列である必要があります`);
    } else if (field.type === 'number' && typeof value !== 'number') {
      errors.push(`${fieldPath} は数値である必要があります`);
    } else if (field.type === 'boolean' && typeof value !== 'boolean') {
      errors.push(`${fieldPath} は真偽値である必要があります`);
    } else if (field.type === 'date') {
      if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
        errors.push(`${fieldPath} はISO 8601形式の日付である必要があります`);
      }
    } else if (field.type === 'collection') {
      if (value === null || typeof value !== 'object' || Array.isArray(value)) {
        errors.push(`${fieldPath} はオブジェクトである必要があります`);
      } else {
        validateObject(value, field.spec ?? [], fieldPath, errors);
      }
    } else if (field.type === 'array') {
      if (!Array.isArray(value)) {
        errors.push(`${fieldPath} は配列である必要があります`);
      } else {
        value.forEach((item, index) => {
          const itemPath = `${fieldPath}[${index}]`;
          if (item === null || typeof item !== 'object' || Array.isArray(item)) {
            errors.push(`${itemPath} はオブジェクトである必要があります`);
          } else {
            validateObject(item, field.spec ?? [], itemPath, errors);
          }
        });
      }
    }
  }
}

function validateParams(params, schema) {
  const errors = [];

  if (params === null || typeof params !== 'object' || Array.isArray(params)) {
    return ['params はオブジェクトである必要があります'];
  }

  validateObject(params, schema, '', errors);
  return errors;
}

// 使用例
const schema = await getDesignParameters('550e8400-...');
const params = {
  customerName: '山田太郎',
  invoiceNumber: 'INV-001',
  amount: 10000
};

const errors = validateParams(params, schema);
if (errors.length > 0) {
  console.error('バリデーションエラー:', errors);
}

ベストプラクティス​

1. パラメータスキーマのキャッシュ​

デザインのバージョンが変わらない限り、パラメータスキーマは変わりません。キャッシュして再利用することを推奨します。

const schemaCache = new Map();

async function getDesignParametersCached(designId, version) {
  const cacheKey = `${designId}:${version}`;

  if (schemaCache.has(cacheKey)) {
    return schemaCache.get(cacheKey);
  }

  const schema = await getDesignParameters(designId, version);
  schemaCache.set(cacheKey, schema);

  return schema;
}

2. PDF生成前の検証​

パラメータスキーマを事前に取得してバリデーションを行うことで、エラーを早期に検出できます。

async function generatePDFSafely(params) {
  // 1. パラメータスキーマを取得
  const schema = await getDesignParameters(params.designId, params.version);

  // 2. バリデーション
  const errors = validateParams(params.data, schema);
  if (errors.length > 0) {
    throw new Error(`パラメータエラー: ${errors.join(', ')}`);
  }

  // 3. PDF生成
  return await generatePDF(params);
}

よくある質問​

デザインパラメータのスキーマはいつ変わりますか​

デザインのバージョンが変わらない限りスキーマは変わりません。同じ designId と version の組み合わせであれば、取得したスキーマをキャッシュして再利用できます。

特定バージョンのパラメータを取得するにはどうすればよいですか​

クエリパラメータに version を指定します。省略した場合は最新バージョンのパラメータが返されます。

次のステップ​