Duyệt tài liệu
Hướng dẫn
Giữ kết quả với dữ liệu nhập, liên kết và sử dụng ban đầu của nó, sau đó đưa nó cho một tiến trình khác mà không cần truy vấn khác.
Trên trang này
Truy vấn một lần, sử dụng kết quả qua tác vụ
Làm một báo cáo, chạy lại phân tích của bạn hoặc cung cấp cho một tác nhân sau đó bước cùng một bằng chứng. Dòng làm việc này tiết kiệm một tìm kiếm như một lưu trữ xách tay; đọc rằng lưu trữ cũng không cần thiết FlashData Không chìa khóa cũng không gốc CLI bang.
archive/saved-search/
request.json Truy vấn và tham số gốc
response.json chưa đổi API trả lời
citations.ndjson Đầu đề, nguồn URLs và trích
manifest.json chạy IDkích cỡ tập tin và SHA-256Trước khi bắt đầu
Dùng một thư mục làm việc mới, FlashData CLI có google_search Cho phép và tín dụng sẵn có. Dùng lại hồ sơ xác thực hay FLASHDATA_API_KEY. Bash Kiểm tra sử dụng jq; Windows sử dụng PowerShell 7. Name Python 3.10+ và thư viện chuẩn của nó.
Tiếp tục khi data.accessVerified là true. Vì CLI Nhắc lại, giữ cùng hồ sơ, OS người dùng và thư mục tình trạng. Một tác nhân nên nạp thẻ tín dụng từ cửa hàng bí mật của nó.
flashdata auth status --json1. Giữ đầu vào và lưu một câu trả lời
Lưu request.json Bên dưới, sau đó là chỉ huy. --input sử dụng yêu cầu chính xác này; giữ cho tập tin không thay đổi sau đó. --output lưu API Xác ở trong. search.json; --json In ấn CLI Siêu dữ liệu. Tìm kiếm đã lưu là nhiệm vụ chạy cục bộ này. 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. Kiểm tra phản ứng đã lưu
Nguồn chờ đợi: google_search, status: done Và một danh sách kết quả. In tên của mỗi kết quả hữu cơ, liên kết và trích đoạn. Kết quả thật sự khác nhau; một bộ sưu tập thành công trống rỗng khác với yêu cầu thất bại hoặc một cánh đồng bị mất.
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. Name
Lưu archive.py Bên dưới, sau đó chạy nó với chạy ID từ bước 1. Nó bảo tồn các tập tin thô, trích xuất các liên kết mã nguồn và viết manifest.json cuối cùng với tổng kiểm tra tập tin và cách sử dụng. Mong đợi complete: true; số lần trích dẫn phụ thuộc vào kết quả tìm kiếm. Không có yêu cầu mạng nào được thực hiện.
Lưu archive.py
Tạo archive.py bên cạnh request.json và search.json trong thư mục làm việc của anh. Hãy sao chép toàn bộ mã lệnh bên dưới và lưu nó lại.
Name Google Search Kết quả. Các thư mục kho lưu tồn tại còn nguyên vẹn. Giữ request.json, search.json và chạy cùng nhau cho đến khi thuyết phục hoàn thành.
# 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}))Tạo kho lưu
Chạy từ thư mục chứa archive.py, request.json và search.json.
python3 archive.py --run-id saved-searchpython archive.py --run-id saved-search4. Dùng lại kho lưu mà không có ủy nhiệm
Lưu reuse.py bên dưới. Sao chép thư mục archive/saved-search đầy đủ tới quá trình cần thiết, rồi chạy độc giả này. Nó xác minh mọi tập tin trước khi in các yêu cầu, sử dụng và trích dẫn gốc. Nó hoạt động sau khi... API- Chỉ cần cầu xin lại hay cho phép sử dụng bởi vì nó chỉ đọc bản sao lưu của anh.
Lưu reuse.py
Tạo reuse.py trong thư mục làm việc chứa archive/. Trên một máy khác, sao chép cả hai reuse.py và toàn bộ archive/saved-search thư mục, giữ bố trí này.
# 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))Đọc kho lưu
Lưu reuse.py, rồi chạy từ thư mục của nó. Đối số cuối cùng là đường dẫn tới kho lưu trữ.
python3 reuse.py archive/saved-searchpython reuse.py archive/saved-searchXuất từ CLI thay vào đó, nhật ký
Nếu bạn vẫn còn bản gốc CLI & Xuất ra danh sách hồ sơ và thư mục tiểu dụng: hiện thời Điều này không làm cho truy vấn mới, nhưng nó xác nhận truy cập trực tiếp đầu tiên. Có thể đọc tập tin kết quả hoặc kho lưu cục bộ mà không cần kiểm tra đó.
flashdata runs show saved-search --result --output search-copy.json --jsonQuyết định khi nào nên sử dụng lại hay tươi
archived_at Ghi chép khi anh lưu các tập tin, chứ không phải khi một trang nguồn thay đổi. Ứng dụng của bạn quyết định các bằng chứng phải có gần đây như thế nào; việc sao chép tập tin không làm tươi nội dung của nó.
| Tác vụ | Hành động |
|---|---|
| Chạy lại phân tích, tái tạo một báo cáo hoặc tiếp tục một bước tác nhân | Hãy tái sử dụng phản ứng đã được cứu. Giữ nguồn URLs, truy vấn và sử dụng với nó. |
| Tạo một cuộc họp hàng ngày mới hoặc trả lời một yêu cầu đã thay đổi | Tạo mới task/run IDThư mục và kho lưu trữ. Giữ ảnh cũ như lịch sử. |
| Đếm việc sử dụng trên các tập tin kết xuất | Đếm câu hỏi gốc một lần. Việc sao chép một phản ứng hoặc làm một báo cáo khác không tạo ra một tính năng khác. |
Biết cái gì sẽ hết hạn
| Kết quả | Cần phải giữ gì? | Nhớ |
|---|---|---|
| Truy vấn Realtime | Tập tin đáp ứng và nhập gốc | Bản sao lưu của bạn làm theo chính sách lưu trữ của bạn |
| Async / Batch công việc | Jom IDNhận biên lai và kết quả JSON | Giờ 24 sau khi hoàn tất |
| Bulk | Hiển thị và tất cả NDJSON phần | 24 giờ sau khi toàn bộ công việc hoàn tất; kiểm tra expiresAt |
| YouTube Download | Giao hàng JSON và phương tiện đến nơi | Giao hàng JSON: công việc được giữ lại. Phương tiện: xe đạp chở xô của bạn |
| MCP Bộ nhớ tạm nén | Kết quả đã được lắp ráp đầy đủ | 10 phút; chỉ có bốn kết quả lớn mới nhất trên mỗi API Phím đã được giữ lại |
Giữ một toa xe nhỏ thay thế
Giữ cho phản ứng nguyên thủy không thay đổi. Tiết kiệm một xe hơi nhỏ với dữ liệu nhập, nguồn, tiết kiệm thời gian và sử dụng, để một tiến trình sau này có thể hiểu được cái gì tạo ra tập tin. Giữ nguồn URLs và video thời gian dán nhãn khi chuyển đổi kết quả.
(
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
)Lưu trực tiếp vào HTTP
Dùng cái này thay cho cái CLI truy vấn trong bước 1. Lưu cùng một dạng request.json Đầu tiên; điều này chạy một truy vấn mới sử dụng Bash, cURL 7.76+ và jq. Dùng FLASHDATA_API_KEY và chọn một thư mục không có search.json. Sau khi hợp lệ hóa, cùng một tập lệnh lưu trữ hoạt động với kết quả này; chọn nhiệm vụ riêng của bạn ID Vì --run-id.
A - bô - nê - ô cURL thoát nghĩa là kết quả chưa sẵn sàng để sử dụng. Kiểm tra câu trả lời đã lưu trước khi thử lại; thời hạn kết nối có thể xảy ra sau khi yêu cầu được chấp nhận. Dùng lệnh xác thực trong bước 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
)Lưu một công việc nền đã có
Dùng submission.json từ một hướng dẫn viên đặc biệt và cùng một tài khoản chứng thực. Những lệnh này phục hồi công việc đã có; chúng không đệ trình một yêu cầu khác. Hạt CLI chờ hoàn tất và xử lý kết quả chuyển hướng. Lưu kết quả bên trong 24 Giờ hoàn thành.
(
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
)Kiểm tra tình trạng ngừng nếu công việc chưa hoàn tất. Nếu nó vẫn còn xếp hàng hoặc đang chạy, chờ đợi và chạy đoạn trích chỉ đọc này một lần nữa; thanh tra một công việc bị lỗi thay vào đó. A 302 được tải về mà không chuyển tiếp API Chìa khóa. Đáp ứng tạm thời đã được xác nhận trước job-result.json được tạo ra.
(
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
)Lưu mỗi Bulk phần kết quả
Thay thế BULK_ID với ID trong hóa đơn nộp. Sau khi xong việc, CLI theo sau bản kê và lưu mọi phần thành một tập tin NDJSON. Cũng hãy giữ bảng liệt kê khi bạn cần đếm và một phần siêu dữ liệu.
Tập tin có thể chứa hàng vừa thành công vừa thất bại. Đáp ứng chỉ mục nhập và đếm trước khi đánh dấu toàn bộ tác vụ hoàn tất. Không chạy lại toàn bộ tập tin nhập để phục hồi một bị lỗi hàng.
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --jsonGiữ kỉ lục giao hàng và truyền thông
delivery.json không phải video hay âm thanh byte. Tiết kiệm URL, kích thước và tổng kiểm tra bên cạnh nhiệm vụ. Các phương tiện truyền thông sống trong kho lưu trữ của bạn và theo sau chiếc xe đạp cứu hộ đó.
Để có một điểm đến riêng, hãy sử dụng giấy ủy nhiệm của nhà cung cấp đó hoặc ký URL để kiểm tra đối tượng. Thiếu kết quả tạm thời JSON không có nghĩa là truyền thông đã bị xóa.
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.jsonTập hợp MCP miếng trước khi lưu
Khi một công cụ trở lại result_id, mảng và next_offsetĐọc những đoạn còn lại với get_result sử dụng cùng một API Chìa khóa. Sử dụng chính xác next_offset được trả lại bởi công cụ; các giá trị bên dưới là người giữ chỗ.
- Phụ thêm mỗi miếng theo thứ tự bù đắp. Theo next_offset Cho đến khi nó là null.
- Phân tích văn bản đã tham gia một lần như JSONSau đó, hãy viết đầy đủ kết quả vào hồ sơ của chính bạn hoặc kho lưu trữ của bạn.
- Lưu trước expires_at. Những câu trả lời mới có thể xua đuổi những kết quả cũ trước khi 10- Giới hạn phút; bộ nhớ tạm giữ bốn trên một API Chìa khóa.
{
"name": "get_result",
"arguments": {
"result_id": "RESULT_ID_FROM_TOOL",
"offset": 16000
}
}Sửa chữa vấn đề lưu và lấy lại
| Vấn đề | Sửa |
|---|---|
| Tập tin xuất đã có | Kiểm tra nó trước. Để hoàn tất CLI chạy, sử dụng runs show với tên tập tin xuất mới thay vì gửi một yêu cầu khác. |
| CLI không thể tìm thấy chạy | Dùng bản gốc OS người dùng, hồ sơ và thư mục tiểu dụng. Nếu anh giữ một công việc từ xa IDThu thập công việc đó trực tiếp. |
| 401 / 403 khi dùng lại | Chạy chiếu sáng auth status --json và khôi phục truy cập hợp lệ. Một tập tin cục bộ đã lưu vẫn còn có thể đọc mà không có truy cập API. |
| 409 / 410 | 409: đợi công việc đã có. 410: sử dụng bản sao lưu của bạn; kết quả tạm thời đã hết hạn. |
| Lỗi đĩa sau khi truy vấn | Cứ tiếp tục chạy. ID công việc ID. Sửa sang việc lưu trữ và phục hồi công việc đã có trước khi xem xét một sự phục tùng mới. |
| Kho không có danh sách hoặc tổng kiểm tra thất bại | Phục hồi hoặc sao chép lại các tập tin gốc. Giữ kho lưu trữ không đầy đủ để kiểm tra; việc xây dựng lại kho lưu trữ không cần thiết một yêu cầu mới. |
| MCP · result_unavailable | Kiểm tra kết quả IDKhoảng cách, API Chìa khóa và giải phẫu. Dùng một bản sao lưu nếu bộ nhớ tạm đã hết hạn; không lặp lại một yêu cầu trả tiền. |