コンテンツへスキップ
JA
APIキーを取得する
ドキュメントを探す

ガイド

結果を保存して再利用

元の入力、ソースリンク、使用状況で結果を保持し、別のクエリなしで別のプロセスにそれを渡す。

このページの内容

一度クエリして、タスク全体で結果を使う

レポートを作成し、パーサを再実行するか、後者のエージェントが同じ証拠をステップします。 このワークフローは、FlashDataキーと元のCLI状態のどちらのアーカイブも必要としている、ポータブルなアーカイブとして1つの検索を保存します。

あなたを維持するもの
archive/saved-search/
  request.jsonオリジナルクエリとパラメータ
  response.jsonは変更されていないAPI応答を
  citations.ndjsonのタイトル、ソースURLsとスニペット
  manifest.json       ログイン ID、使用法、ファイル サイズおよび SHA-256

はじめる前に

google_searchの許可と利用可能なクレジットで、新しい作業フォルダ、FlashData CLIを使用してください。 認証されたプロファイルまたはFLASHDATA_API_KEYを再利用します。 Bashの点検はjqを使用します; WindowsはPowerShell 7を使用します。 ローカルアーカイブスクリプトは、Python 3.10+ と標準ライブラリを使用します。

data.accessVerified が true である時続行して下さい。 CLI retries では、同じプロファイル、OS ユーザとステートディレクトリーを保持します。 エージェントは、その秘密ストアから既存の資格をロードする必要があります。

保存されたアクセスを確認する
flashdata auth status --json

1. 入力を保ち、1つの応答を救いて下さい

保存する request.json 以下は、コマンドを1つ実行します。 --input この正確なリクエストを使用して、ファイルを後で変更しないようにします。 --output 保存する API ボディ で search.json; --json プリント CLI metadata. 保存検索は、このタスクのローカル実行です ID.

request.json
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  }
}
1つの検索を実行します
flashdata query --input request.json \
  --run-id saved-search --output search.json --json

2. 保存された応答を検証する

期待ソース: google_search、status: done、および結果の配列。 各有機物の結果のタイトル、リンクおよびスニペットを印刷して下さい。 実際の結果は異なります。空の成功したコレクションは、失敗したリクエストや欠落しているフィールドとは異なるです。

search.jsonを検証して読み直します
jq -e '.source == "google_search" and .status == "done"
  and (.results | type == "array")
  and all(.results[]; (.organic | type == "array"))' search.json > /dev/null &&
jq -c '.results[] | .organic[] | {title, link, snippet}' search.json

3. 入力、応答、引用をアーカイブする

保存する archive.py 以下は、実行時に実行します。 ID ステップから 1. 生のファイルを保存し、ソースリンクを抽出し、書き込みを抽出します manifest.json ファイルのチェックサムと使用で最後に。 complete: trueを期待する;引用数は検索結果に依存します。 ネットワークリクエストは行いません。

保存 archive.py

作成する archive.py そばに request.json とりあえず search.json 作業フォルダに。 下記のコードをコピーして保存します。

たとえば、Google Search 結果がアーカイブされます。 既存のアーカイブディレクトリはそのままに保管されます。 request.json、search.json を保ち、マッチングはアーカイブが完了するまで一緒に実行します。

archive.py
# archive.py — Python 3.10+, standard library only; no network requests.
import argparse
import hashlib
import json
import re
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlsplit

parser = argparse.ArgumentParser()
parser.add_argument('--run-id', required=True)
args = parser.parse_args()
if not re.fullmatch(r'[A-Za-z0-9_-]+', args.run_id):
    raise ValueError('Use the CLI run ID from this task.')
request_bytes = Path('request.json').read_bytes()
result_bytes = Path('search.json').read_bytes()
request = json.loads(request_bytes.decode('utf-8-sig'))
result = json.loads(result_bytes.decode('utf-8-sig'))
if (request.get('source') != 'google_search' or result.get('source') != request['source']
        or result.get('status') not in ['done', 'completed']
        or not isinstance(result.get('results'), list)):
    raise ValueError('Inspect the request and result before archiving.')
citations = []
for page in result['results']:
    if not isinstance(page, dict) or not isinstance(page.get('organic'), list):
        raise ValueError('Expected an organic results array, including when it is empty.')
    for item in page['organic']:
        if not isinstance(item, dict) or not isinstance(item.get('link'), str):
            raise ValueError('A result is missing its source URL.')
        url = urlsplit(item['link'])
        if url.scheme not in ['http', 'https'] or not url.netloc:
            raise ValueError('Inspect an unexpected source URL.')
        citations.append({key: item.get(key, '') for key in ['title', 'link', 'snippet']})
files = {'request.json': request_bytes, 'response.json': result_bytes,
         'citations.ndjson': ''.join(json.dumps(row, ensure_ascii=False) + '\n'
                                    for row in citations).encode('utf-8')}
manifest = {'version': 1, 'run_id': args.run_id, 'source': request['source'],
            'archived_at': datetime.now(timezone.utc).isoformat(),
            'usage': result.get('usage'), 'citation_count': len(citations),
            'files': {name: {'bytes': len(data), 'sha256': hashlib.sha256(data).hexdigest()}
                      for name, data in files.items()}}
folder = Path('archive') / args.run_id
folder.mkdir(parents=True)  # Existing archives are preserved. Choose a new run ID for new work.
for name, data in files.items():
    with (folder / name).open('xb') as output:
        output.write(data)
# Write the manifest last. Without it, the archive is incomplete.
with (folder / 'manifest.json').open('x', encoding='utf-8') as output:
    json.dump(manifest, output, ensure_ascii=False, indent=2)
print(json.dumps({'archive': str(folder), 'citations': len(citations), 'complete': True}))

アーカイブを作成する

archive.py、request.json、search.jsonを含むフォルダから実行します。

新しいアーカイブを作成する
python3 archive.py --run-id saved-search

4. 資格情報なしでアーカイブを再利用する

reuse.pyを以下に保存します。 必要なプロセスに完全なarchive/saved-searchフォルダをコピーし、このリーダーを実行します。 元のクエリ、使用方法、引用を印刷する前に、すべてのファイルを検証します。 API-key のリボベーションやホストレストの expiry の後、保存されたコピーのみを読み込むため動作します。

保存 reuse.py

archive/. を含む作業フォルダに reuse.py を作成します。 別のマシンでは、reuse.pyと完全なarchive/saved-searchディレクトリをコピーし、このレイアウトを維持します。

reuse.py
# reuse.py — run without a FlashData key or CLI.
import hashlib
import json
import sys
from pathlib import Path

folder = Path(sys.argv[1])
manifest = json.loads((folder / 'manifest.json').read_text(encoding='utf-8'))
expected = {'request.json', 'response.json', 'citations.ndjson'}
if manifest.get('version') != 1 or set(manifest.get('files', {})) != expected:
    raise ValueError('Unknown or incomplete archive manifest.')
files = {}
for name in sorted(expected):
    data = (folder / name).read_bytes()
    record = manifest['files'][name]
    if len(data) != record['bytes'] or hashlib.sha256(data).hexdigest() != record['sha256']:
        raise ValueError('Archive changed or was not fully copied: ' + name)
    files[name] = data
request = json.loads(files['request.json'].decode('utf-8-sig'))
citations = [json.loads(line) for line in files['citations.ndjson'].decode('utf-8').splitlines()]
if len(citations) != manifest['citation_count']:
    raise ValueError('Citation count does not match the manifest.')
print(json.dumps({'run_id': manifest['run_id'], 'query': request['query'],
                  'archived_at': manifest['archived_at'], 'usage': manifest['usage'],
                  'citations': citations}, indent=2))

保存されたアーカイブを読む

reuse.pyを保存し、フォルダから実行します。 最後の引数は、コピーされたアーカイブへのパスです。

コピーされたアーカイブを読む
python3 reuse.py archive/saved-search

代わりにCLIジャーナルからエクスポート

元の CLI プロファイルとステートディレクトリがまだある場合は、保存された実行を新しいファイル名にエクスポートします。 新しいクエリは行いませんが、最初にライブアクセスを検証します。 既存の結果ファイルやアーカイブは、そのチェックなしでローカルに読み込むことができます。

完了した実行をエクスポートする
flashdata runs show saved-search --result --output search-copy.json --json

再使用またはリフレッシュするときに決定

ソースページが変更されたときではなく、ファイルを保存するときにarchived_atレコードが記録されます。 アプリケーションは、最近の証拠がどうなるかを決定します。 ファイルをコピーすると、その内容をリフレッシュしません。

タスクアクション
パーサを再実行し、レポートを再生するか、またはエージェントのステップを続行する保存された応答を再利用します。 ソースURLs、クエリパラメータ、使用量をそのまま保持します。
変更されたクエリに新しい毎日のブリーフィングや回答を生成task/run ID、作業フォルダ、アーカイブを作成します。 古いスナップショットを履歴として保存します。
派生したファイルを渡る使用法を数える元のクエリを一度にカウントします。 応答をコピーするか、別のレポートを作成すると、別の手数料は作成されません。

期限切れを知る

結果発表維持する何注意点
Realtime クエリ応答ファイルと元の入力保存したコピーは、保存ポリシーに従っています
Async / Batchジョブ求人 ID, 投稿レシートと結果 JSON24 完了後時間
BulkマニフェストとすべてのNDJSONパーツ24 ジョブ全体が完了した後の時間; チェック expiresAt
YouTube DownloadJSONとメディアを目的地に配信配信 JSON: ジョブ保持. 媒体:あなたのバケツのライフサイクル
MCPチャンクキャッシュ完全に組み立てられた結果10分;APIキーごとの4つの最も最近の大きい結果だけ保持されます

代わりに小さなサイドカーをキープ

元の応答は変更されません。 入力、ソース、保存時間、使用量で小さなサイドカーを保存して、後で生成されたファイルを理解できるようにします。 結果を変換するときにソースURLsとビデオタイムスタンプを保持します。

Bash / jq · search-record.json
(
set -euC
jq --arg run_id 'saved-search' --slurpfile request request.json \
  '{run_id: $run_id, source, input: $request[0],
    saved_at: (now | todateiso8601), result_file: "search.json", usage}' \
  search.json > search-record.json
cat search-record.json
)

HTTPで直接保存

この代わりに、CLI クエリの代わりに、ステップ 1 を使用します。 同じ保存 request.json 最初に; これは 1 つの新しいクエリを実行します。 Bash, cURL 7.76+ と jq. FLASHDATA_API_KEY をリユースし、search.json なしでフォルダを選択します。 検証後、同じアーカイブスクリプトは、この結果で動作します。 --run-id の独自のタスク ID を選択します。

非ゼロ cURL 出口は結果が使用のために準備が整っていないことを意味します。 再試行の前に保存された応答を調べる。クエリが受け入れられた後、接続タイムアウトが起こりうる。 バリデーションコマンドは、ステップ2で使用します。

必要に応じてキーを設定する
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY
API 応答を保存
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test -f request.json
curl --fail-with-body --silent --show-error --max-time 120 \
  --request POST 'https://data.flashdata.dev/v1/queries/realtime' \
  --header "X-API-Key: $FLASHDATA_API_KEY" \
  --header 'Content-Type: application/json' --header 'Accept: application/json' \
  --data-binary @request.json > search.json
jq . search.json
)

既存の背景ジョブを保存

submission.json は、非同期ガイドと同一のアカウント認証から利用します。 これらのコマンドは、既存の作業を受け取り、別のクエリを送信しません。 CLIは完了を待ち、結果をリダイレクト処理します。 完了の24時間以内に結果を保存します。

待ち、取得および保存
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --json
flashdata jobs result "$JOB_ID" --output job-result.json --json
jq '{source, status, results, usage}' job-result.json
)

すべてのBulk結果の部分を保存

BULK_IDを提出レシートにIDに置き換えてください。 ジョブが完了すると、CLI はマニフェストに従い、各部分を NDJSON ファイルとして保存します。 カウントや部分のメタデータが必要な場合は、マニフェストも保持します。

ファイルが、成功と失敗した行の両方を含むことができます。 入力インデックスとカウントを調整し、タスク全体の完全なマークを付ける前にカウントします。 入力ファイル全体を再実行し、失敗した行を回復しないでください。

完成したジョブを収集する
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --json

配達記録および媒体を保って下さい

delivery.jsonは、ビデオやオーディオバイトではなく、配信レコードが含まれています。 URL、サイズ、チェックサムをタスクと一緒に保存します。 メディアは、保存先のストレージに住んでおり、そのストレージのライフサイクルに従います。

プライベートの宛先では、プロバイダの資格情報または署名されたURLを使用して、オブジェクトを検査します。 欠落した一時的な結果 JSON は、保存されたメディアが削除されたという意味ではありません。

保存したダウンロード結果の点検 · jq
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.json

MCPのチャンクを節約する前に組み立てて下さい

ツールが result_id、チャンク、next_offset を返すと、同じ API キーを使用して、残りのチャンクを get_result で読み込みます。 ツールによって返される正確なnext_offsetを使用してください。以下はプレースホルダーです。

  1. オフセット順に各チャンクを追加します。 next_offset を null までフォローしてください。
  2. 結合されたテキストをJSONとして一度にパースし、自分のファイルやストレージにフル結果を書きます。
  3. expires_atの前に保存します。 10-minuteの限界の前の新しい大きい応答は古い結果を軽減できます; キャッシュはAPIキーごとの4を維持します。
MCP tools/call引数
{
  "name": "get_result",
  "arguments": {
    "result_id": "RESULT_ID_FROM_TOOL",
    "offset": 16000
  }
}

省力化と反省の問題の修正

問題の問題フィックス
既に存在する出力ファイル最初にそれを点検して下さい。 完了したCLIの実行には、別のクエリを提出する代わりに、新しい出力ファイル名でruns showを使用します。
CLI で実行履歴が見つからない元の OS ユーザ、プロフィール、ステートディレクトリを使用します。 リモートジョブIDを保持している場合は、そのジョブを直接取得します。
401/再使用の403Flashdata auth status --jsonを実行し、有効なアクセスを復元します。 APIアクセスなしでローカルファイルが既に保存されているまま読み込むことができます。
409 / 410409: 既存のジョブを待ちます。 410: 保存されたコピーを使用してください。一時的な結果は期限切れです。
クエリ後のディスクエラーID または ID を実行してください。 新規の投稿を検討する前に、既存の作業を記憶し、回復させる。
アーカイブにはマニフェストやチェックサムが失敗しない元のファイルを再び復元またはコピーします。 点検のための不完全なアーカイブを保って下さい; アーカイブを再建することは新しい照会を必要としません。
MCP · result_unavailable結果を点検して下さい ID、オフセット、APIのキーおよびexpiry。 キャッシュが期限切れになったら保存されたコピーを使用してください。 有料のクエリを繰り返すことでループしないでください。