アップロード・ダウンロード

会員データを一括してアップロードしたい

KREISEL には、管理画面から会員データをアップロードする機能がありますが、JSON API を利用しても同様の処理が可能です。

API を利用した会員データの一括アップロードは、以下のステップで行います。

フェーズ	説明	必要な処理
1	アップロードするファイルをKREISELに転送し、`stored_file_id` を取得します。	`/api/v1/upload_stored_files` を呼び出します。
2	転送したファイルを使って、会員データの一括インポート処理を開始します。	`/api/v1/import_members` を呼び出します。
3	一括処理の進捗状況を確認します。	`/api/v1/get_batch_job_status` を呼び出します。
4	（任意）インポート結果のログファイルをダウンロードします。	`/api/v1/get_batch_job_result` を呼び出します。

備考

SOAP API では、ファイルのアップロードに複数回の API コールが必要でしたが、JSON API では /api/v1/upload_stored_files の一度の呼び出しで完結するように改善されました。

各ステップを詳しく見ていきましょう。

1. ファイルのアップロード (`/api/v1/upload_stored_files`)

まず、インポートしたい会員データが記載された CSV（または TSV）ファイルを KREISEL にアップロードします。

この API は、ファイル名を指定し、ファイルの中身を Base64 エンコードして送信します。

upload_stored_files の呼び出しに成功すると、後続の import_members API で必要となる stored_file_id が返されます。

<?php
// APIエンドポイントと認証情報
$apiUrl = 'https://krs.bz/{環境ID}/api/v1/upload_stored_files';
$apiToken = 'YOUR_API_TOKEN';

// アップロードするファイルのパス
$filePath = 'upload.csv';

// ファイルの内容を読み込み、Base64エンコード
$fileContent = file_get_contents($filePath);
$fileContentBase64 = base64_encode($fileContent);

// リクエストボディの作成
$requestData = [
    'file_name' => basename($filePath),
    'file_content_base64' => $fileContentBase64,
    'character_code' => 'utf8', // ファイルの文字コード (sjis, eucjpなども指定可)
    'line_feed_code' => 'lf',   // ファイルの改行コード (crlf, crも指定可)
];

$ch = curl_init($apiUrl);

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($requestData),
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $responseData = json_decode($response, true);
    $storedFieId = $responseData['stored_file_id'];
    echo "ファイルアップロード成功！ Stored File ID: ", $storedFieId;
} else {
    echo "ファイルアップロード失敗: ", $response;
    exit;
}

// この後、取得した $storedFieId を使って import_members を呼び出す

注意

アップロードできるファイルの最大容量は 50MB です。50MB を超えるファイルをアップロードしようとすると、API はエラーを返します。また、同時に実行できるアップロード処理は 1 つだけです。複数のファイルをアップロードする場合は、1 つ目の処理が完了してから次の処理を開始してください。

2. 会員データのインポート (`/api/v1/import_members`)

upload_stored_files で取得した stored_file_id を使い、import_members API を呼び出してインポート処理を開始します。

この API を呼び出すと、一括処理のステータスを追跡するための batch_job_id が返されます。

import_members の主要なパラメータは以下の通りです。

引数	データ型	説明
`member_table_id`	Integer	インポート先のデータベースID。
`stored_file_id`	Integer	`upload_stored_files` で取得したID。
`is_update`	Integer	登録・更新の方法を指定するフラグ。<br> `0`: 登録のみ, `1`: 登録と更新, `2`: 更新のみ
`override_options`	Array	各データベース項目をどのように更新するかをキーと値のペアで指定します。

override_options の詳細な設定方法は、OpenAPI 仕様書の /api/v1/import_members の項目を参照してください。キーには e_{項目ID} を指定します。

<?php
// 前のステップから続く...
$importApiUrl = 'https://krs.bz/{環境ID}/api/v1/import_members';

// e_24 (複数選択) はマージ、e_25 は強制上書き、他は通常更新
$overrideOptions = [
    "e_21" => "normal",
    "e_22" => "normal",
    "e_23" => "normal",
    "e_24" => "merge",
    "e_25" => "force",
    "e_26" => "normal"
];

$importRequestData = [
    'member_table_id' => 1,
    'stored_file_id' => $storedFieId,
    'is_update' => 1, // 登録と更新を行う
    'override_options' => $overrideOptions,
];

$ch = curl_init($importApiUrl);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($importRequestData),
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $responseData = json_decode($response, true);
    $batchJobId = $responseData['batch_job_id'];
    echo "インポート処理を開始しました。 Batch Job ID: ", $batchJobId;
} else {
    echo "インポート処理の開始に失敗しました: ", $response;
    exit;
}

警告

import_members や export_members といった一括処理 API は、同時に複数実行できません。いずれかの一括処理を実行している間は、他のインポートやエクスポート処理を開始することはできません。

3. 進捗状況の確認 (`/api/v1/get_batch_job_status`)

import_members で取得した batch_job_id を使って、定期的に get_batch_job_status API を呼び出し、処理の進捗を確認します。 progress が 100 になれば処理は完了です。

<?php
// 前のステップから続く...
$statusApiUrl = 'https://krs.bz/{環境ID}/api/v1/get_batch_job_status';

$progress = 0;
while ($progress < 100) {
    $statusRequestData = ['batch_job_id' => $batchJobId];

    $ch = curl_init($statusApiUrl);
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $apiToken,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => json_encode($statusRequestData),
    ]);

    $response = curl_exec($ch);
    $statusData = json_decode($response, true);
    curl_close($ch);

    $progress = $statusData['progress'] ?? 0;
    $operation = $statusData['operation'] ?? '不明';

    echo sprintf("%s\t進捗 : %d％\n", $operation, $progress);

    if ($progress < 100) {
        sleep(5); // 5秒待機して再確認
    }
}

echo "インポート処理が完了しました。", PHP_EOL;

会員データを一括してダウンロードしたい

API を利用して会員データの一括ダウンロードを行うためのフェーズは以下の通りです。

フェーズ	説明	必要な処理
1	会員データをエクスポートする一括処理を開始します。	`/api/v1/export_members` を呼び出します。
2	一括処理の進捗状況を確認します。	`/api/v1/get_batch_job_status` を呼び出します。
3	作成されたダウンロードファイルを取得します。	`/api/v1/get_batch_job_result` を呼び出します。

1. 会員データのエクスポート (`/api/v1/export_members`)

export_members を呼び出すと、会員データのエクスポート処理が開始され、batch_job_id が返されます。

引数	データ型	説明
`member_table_id`	Integer	ダウンロード対象のデータベースID。
`condition_id`	Integer	絞り込みに使う抽出条件ID。全員を対象とする場合は `1` を指定します。
`columnset_id`	Integer	ダウンロードする項目を絞り込む項目セットID。全項目を対象とする場合は `1` を指定します。
`is_csv`	Boolean	`true`でCSV形式、`false`でTSV形式のファイルを作成します。

<?php
$exportApiUrl = 'https://krs.bz/{環境ID}/api/v1/export_members';
$apiToken = 'YOUR_API_TOKEN';

$exportRequestData = [
    'member_table_id' => 1,
    'condition_id' => 1,    // 全員を対象
    'columnset_id' => 1,     // 全項目を対象
    'is_csv' => true,        // CSV形式
];

$ch = curl_init($exportApiUrl);
// ... cURLオプション設定 ...
$response = curl_exec($ch);
// ... cURL実行とエラーチェック ...
$responseData = json_decode($response, true);
$batchJobId = $responseData['batch_job_id'];

echo "エクスポート処理を開始しました。 Batch Job ID: ", $batchJobId;

2. 進捗状況の確認 (`/api/v1/get_batch_job_status`)

インポート時と同様に get_batch_job_status API で進捗を確認します。progress が 100 になればファイルの準備は完了です。

3. ダウンロードファイルの取得 (`/api/v1/get_batch_job_result`)

処理が完了したら、get_batch_job_result API を呼び出してファイルの中身を直接取得し、保存します。

備考

SOAP API の getBatchJobResultUrl() とは異なり、JSON API ではダウンロード用の一時 URL を取得するのではなく、API のレスポンスとしてファイル本体が直接返されます。

<?php
// ... 進捗確認ループの後 ...
$resultApiUrl = 'https://krs.bz/{環境ID}/api/v1/get_batch_job_result';

$resultRequestData = ['batch_job_id' => $batchJobId];

$ch = curl_init($resultApiUrl);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiToken,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($resultRequestData),
]);

$fileContent = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    file_put_contents('download_result.csv', $fileContent);
    echo "ファイルをダウンロードしました: download_result.csv";
} else {
    echo "ダウンロードに失敗しました: ", $fileContent;
}

変更があった会員データだけダウンロードしたい

基本的な流れは通常のダウンロードと同じですが、export_members を呼び出す際に、更新日時 を条件に設定した抽出条件の ID を指定します。

管理画面の [会員データ] > [抽出条件管理] で、「更新日時」が「データあり」となっている抽出条件を作成し、その ID を condition_id に指定してください。これにより、一度でも更新されたことがある会員データのみをエクスポートできます。

特定条件の会員データだけ削除したい

delete_members_by_condition API を使用すると、指定した抽出条件に合致する会員を一括で削除できます。

この API は呼び出すと即座に削除が実行されるため、取り扱いには十分ご注意ください。

引数	データ型	説明
`member_table_id`	Integer	データベースID。
`password`	String	APIを実行しているアカウントのログインパスワード。安全確認のために必要です。
`condition_id`	Integer	削除対象を絞り込むための抽出条件ID。

<?php
$deleteApiUrl = 'https://krs.bz/{環境ID}/api/v1/delete_members_by_condition';
$apiToken = 'YOUR_API_TOKEN';
$loginPassword = 'YOUR_LOGIN_PASSWORD'; // APIユーザーのパスワード

$deleteRequestData = [
    'member_table_id' => 1,
    'password' => $loginPassword,
    'condition_id' => 2, // 例: 「退会希望者」の抽出条件ID
];

$ch = curl_init($deleteApiUrl);
// ... cURLオプション設定 ...
$response = curl_exec($ch);
// ... cURL実行とエラーチェック ...
$responseData = json_decode($response, true);
$deletedCount = $responseData['results'];

echo sprintf("%d名の会員を削除しました。", $deletedCount);

会員データを一括してアップロードしたい​

1. ファイルのアップロード (/api/v1/upload_stored_files)​

2. 会員データのインポート (/api/v1/import_members)​

3. 進捗状況の確認 (/api/v1/get_batch_job_status)​

会員データを一括してダウンロードしたい​

1. 会員データのエクスポート (/api/v1/export_members)​

2. 進捗状況の確認 (/api/v1/get_batch_job_status)​

3. ダウンロードファイルの取得 (/api/v1/get_batch_job_result)​

変更があった会員データだけダウンロードしたい​

特定条件の会員データだけ削除したい​