ドキュメントを探す
ガイド
元の入力、ソースリンク、使用状況で結果を保持し、別のクエリなしで別のプロセスにそれを渡す。
このページの内容
一度クエリして、タスク全体で結果を使う
レポートを作成し、パーサを再実行するか、後者のエージェントが同じ証拠をステップします。 このワークフローは、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 --json1. 入力を保ち、1つの応答を救いて下さい
保存する request.json 以下は、コマンドを1つ実行します。 --input この正確なリクエストを使用して、ファイルを後で変更しないようにします。 --output 保存する API ボディ で search.json; --json プリント CLI metadata. 保存検索は、このタスクのローカル実行です ID.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
}flashdata query --input request.json \
--run-id saved-search --output search.json --jsonflashdata query --input request.json `
--run-id saved-search --output search.json --json2. 保存された応答を検証する
期待ソース: google_search、status: done、および結果の配列。 各有機物の結果のタイトル、リンクおよびスニペットを印刷して下さい。 実際の結果は異なります。空の成功したコレクションは、失敗したリクエストや欠落しているフィールドとは異なるです。
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$result = Get-Content -Raw -LiteralPath search.json | ConvertFrom-Json
if ($result.source -ne 'google_search' -or $result.status -ne 'done' -or
-not ($result.results -is [array])) {
throw 'Inspect search.json before treating the task as complete.'
}
foreach ($page in $result.results) {
if (-not ($page.organic -is [array])) { throw 'Missing organic results array.' }
$page.organic | Select-Object title, link, snippet
}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 — 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-searchpython archive.py --run-id saved-search4. 資格情報なしでアーカイブを再利用する
reuse.pyを以下に保存します。 必要なプロセスに完全なarchive/saved-searchフォルダをコピーし、このリーダーを実行します。 元のクエリ、使用方法、引用を印刷する前に、すべてのファイルを検証します。 API-key のリボベーションやホストレストの expiry の後、保存されたコピーのみを読み込むため動作します。
保存 reuse.py
archive/. を含む作業フォルダに reuse.py を作成します。 別のマシンでは、reuse.pyと完全なarchive/saved-searchディレクトリをコピーし、このレイアウトを維持します。
# 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-searchpython 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, 投稿レシートと結果 JSON | 24 完了後時間 |
| Bulk | マニフェストとすべてのNDJSONパーツ | 24 ジョブ全体が完了した後の時間; チェック expiresAt |
| YouTube Download | JSONとメディアを目的地に配信 | 配信 JSON: ジョブ保持. 媒体:あなたのバケツのライフサイクル |
| MCPチャンクキャッシュ | 完全に組み立てられた結果 | 10分;APIキーごとの4つの最も最近の大きい結果だけ保持されます |
代わりに小さなサイドカーをキープ
元の応答は変更されません。 入力、ソース、保存時間、使用量で小さなサイドカーを保存して、後で生成されたファイルを理解できるようにします。 結果を変換するときにソースURLsとビデオタイムスタンプを保持します。
(
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(
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
)ジョブが終了しない場合は、ステータスチェックが停止します。 まだキューイングまたは実行中の場合、この読み取り専用スニペットを再び待ち、実行します。 代わりに失敗したジョブを調べます。 302はAPIキーを転送せずにダウンロードします。 job-result.jsonが作成される前に仮応答が検証されます。
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e job-result.json || { echo 'Choose a new output filename.' >&2; exit 1; }
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
printf '%s' "$JOB_ID" | grep -Eq '^[A-Za-z0-9_-]+$'
SOURCE=$(jq -er '(.submission // .).source' submission.json)
API="https://api.flashdata.dev/v2/jobs/$JOB_ID"
curl --fail-with-body --silent --show-error \
--max-time 30 --header "X-API-Key: $FLASHDATA_API_KEY" "$API" >| job-status.json
jq -e --arg id "$JOB_ID" --arg source "$SOURCE" \
'.job.id == $id and .job.source == $source and .job.status == "completed"' job-status.json >/dev/null
STATUS=$(curl --silent --show-error \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--max-time 120 --dump-header result-headers.txt --output job-result.pending \
--write-out '%{http_code}' "$API/results")
case "$STATUS" in
200) ;;
302)
LOCATION=$(awk 'tolower($1) == "location:" { sub(/\r$/, "", $2); print $2 }' result-headers.txt)
# No FlashData API key on the signed storage request.
curl --fail-with-body --silent --show-error --compressed --max-time 120 \
--proto '=https' --output job-result.pending "$LOCATION" ;;
*) echo "HTTP $STATUS: inspect job-result.pending and result-headers.txt." >&2; exit 1 ;;
esac
jq -e --arg source "$SOURCE" '.source == $source and (.status == "done" or .status == "completed")
and (.results | type == "array")' job-result.pending >/dev/null
cat job-result.pending > job-result.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 '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.jsonMCPのチャンクを節約する前に組み立てて下さい
ツールが result_id、チャンク、next_offset を返すと、同じ API キーを使用して、残りのチャンクを get_result で読み込みます。 ツールによって返される正確なnext_offsetを使用してください。以下はプレースホルダーです。
- オフセット順に各チャンクを追加します。 next_offset を null までフォローしてください。
- 結合されたテキストをJSONとして一度にパースし、自分のファイルやストレージにフル結果を書きます。
- expires_atの前に保存します。 10-minuteの限界の前の新しい大きい応答は古い結果を軽減できます; キャッシュはAPIキーごとの4を維持します。
{
"name": "get_result",
"arguments": {
"result_id": "RESULT_ID_FROM_TOOL",
"offset": 16000
}
}省力化と反省の問題の修正
| 問題の問題 | フィックス |
|---|---|
| 既に存在する出力ファイル | 最初にそれを点検して下さい。 完了したCLIの実行には、別のクエリを提出する代わりに、新しい出力ファイル名でruns showを使用します。 |
| CLI で実行履歴が見つからない | 元の OS ユーザ、プロフィール、ステートディレクトリを使用します。 リモートジョブIDを保持している場合は、そのジョブを直接取得します。 |
| 401/再使用の403 | Flashdata auth status --jsonを実行し、有効なアクセスを復元します。 APIアクセスなしでローカルファイルが既に保存されているまま読み込むことができます。 |
| 409 / 410 | 409: 既存のジョブを待ちます。 410: 保存されたコピーを使用してください。一時的な結果は期限切れです。 |
| クエリ後のディスクエラー | ID または ID を実行してください。 新規の投稿を検討する前に、既存の作業を記憶し、回復させる。 |
| アーカイブにはマニフェストやチェックサムが失敗しない | 元のファイルを再び復元またはコピーします。 点検のための不完全なアーカイブを保って下さい; アーカイブを再建することは新しい照会を必要としません。 |
| MCP · result_unavailable | 結果を点検して下さい ID、オフセット、APIのキーおよびexpiry。 キャッシュが期限切れになったら保存されたコピーを使用してください。 有料のクエリを繰り返すことでループしないでください。 |