Przeglądaj dokumentację
Poradniki
Zachowaj wynik z jego oryginalnym wejściem, odnośnikami źródłowymi i użyciem, a następnie przekaż go do innego procesu bez innego zapytania.
Na tej stronie
Zapytanie raz, wykorzystać wynik w różnych zadaniach
Zbuduj raport, powtórz parser lub daj późniejszy agent krok ten sam dowód. Ten strumień pracy zapisuje jedno wyszukiwanie jako przenośne archiwum; czytanie, że archiwum nie potrzebuje ani klucza FlashData, ani oryginalnego stanu CLI.
archive/saved-search/
request.json oryginalne zapytanie i parametry
response.json niezmieniony API odpowiedź
Tytuły citations.ndjson, źródło URLs i snippety
manifest.json uruchom ID, użycie, rozmiar pliku i SHA- 256Zanim zaczniesz
Użyj nowego folderu roboczego, FlashData CLI z pozwoleniem google_search i dostępnymi kredytami. Ponownie użyj uwierzytelnionego profilu lub FLASHDATA_API_KEY. Bash wykorzystuje jq; Windows wykorzystuje PowerShell 7. Miejscowe skrypty archiwalne wykorzystują Python 3.10 + i jego standardową bibliotekę.
Kontynuować, gdy data.accessVerified jest true. W przypadku powtórzeń CLI należy zachować ten sam profil, użytkownika OS oraz katalog stanu. Agent powinien załadować swój istniejący system kredytowy ze swojego tajnego sklepu.
flashdata auth status --json1. Zachowaj wejście i zapisz jedną odpowiedź
Zapisz request.json poniżej, a następnie uruchom jedną komendę. --input używa tej dokładnej prośby; po tym czasie nie zmieniaj pliku. --output zapisuje ciało API w search.json; --json drukuje CLI metadata. saved- search jest to lokalne działanie 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. Potwierdź zapisaną odpowiedź
Oczekiwane źródło: google_search, status: done oraz tablica wyników. Wydrukuj każdy wynik organiczny tytuł, link i wycinanek. Rzeczywiste wyniki różnią się; pusta, skuteczna kolekcja różni się od nieudanego żądania lub brakującego pola.
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. Archiwizuj dane wejściowe, odpowiedzi i cytaty
Zapisz archive.py poniżej, a następnie uruchom go przy użyciu uruchomienia ID z kroku 1. Zachowuje surowe pliki, wyciąga linki źródłowe i pisze manifest.json ostatni z sumami kontrolnymi i użyciem. Oczekuj complete: true; liczba cytatów zależy od wyników wyszukiwania. Nie złożono żadnych wniosków o utworzenie sieci.
Zapisz archive.py
Utwórz archive.py obok request.json i search.json w swoim katalogu roboczym. Skopiuj do niego cały kod poniżej i zapisz go.
Przykład archiwizuje wyniki Google Search. Istniejące katalogi archiwalne pozostają nienaruszone. Przechowywać request.json, search.json i dopasowanie uruchomić razem, aż archiwizacja zakończy.
# 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}))Utwórz archiwum
Uruchom z folderu zawierającego archive.py, request.json i search.json.
python3 archive.py --run-id saved-searchpython archive.py --run-id saved-search4. Ponownie użyj archiwum bez uwierzytelniania
Zapisz reuse.py poniżej. Skopiuj cały folder archive/saved-search do procesu, który go potrzebuje, a następnie uruchom ten czytnik. Sprawdza każdy plik przed wydrukowaniem oryginalnego zapytania, użycia i cytowania. Działa po cofnięciu klucza API- lub wygaśnięciu wyniku hosted- ponieważ odczytuje tylko zapisaną kopię.
Zapisz reuse.py
Utwórz reuse.py w katalogu roboczym zawierającym archive/. Na innej maszynie skopiuj zarówno reuse.py, jak i kompletny katalog archive/saved-search, zachowując ten układ.
# 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))Przeczytaj zapisane archiwum
Zapisz reuse.py, a następnie uruchom z jego folderu. Końcowym argumentem jest ścieżka do skopiowanego archiwum.
python3 reuse.py archive/saved-searchpython reuse.py archive/saved-searchEksport z dziennika CLI zamiast
Jeśli nadal posiadasz oryginalny profil CLI i katalog stanu, wyeksportuj zapisaną nazwę pliku. To nie powoduje nowych zapytań, ale weryfikuje dostęp na żywo najpierw. Istniejący plik wyników lub archiwum można odczytać lokalnie bez tego sprawdzenia.
flashdata runs show saved-search --result --output search-copy.json --jsonZdecyduj, kiedy ponownie lub odświeżyć
archived_at zapisuje, gdy zapisywałeś pliki, a nie gdy zmieniano stronę źródłową. Aplikacja decyduje o tym, jak niedawno muszą być dowody; kopiowanie pliku nie odświeża jego zawartości.
| Zadanie | Działanie |
|---|---|
| Przekierować parser, zregenerować raport lub kontynuować krok agenta | Ponownie użyj zapisanej odpowiedzi. Zachowaj źródło URLs, parametry zapytania i wykorzystanie wraz z nim. |
| Wyprodukuj nowe dzienne odprawa lub odpowiedz na zmienione zapytanie | Utwórz nowy task/run ID, folder roboczy i archiwum. Zachowaj starsze zdjęcia jako historię. |
| Liczenie wykorzystania plików pochodnych | Odlicz pierwotne zapytanie raz. Kopiowanie odpowiedzi lub sporządzanie kolejnego raportu nie tworzy kolejnej opłaty. |
Wiedz, co wygasa
| Wynik | Co zachować | Zatrzymanie |
|---|---|---|
| Realtime query | Plik odpowiedzi i oryginalne wejście | Zapisany egzemplarz jest zgodny z polityką przechowywania |
| Zadania Async / Batch | Job ID, potwierdzenie złożenia i wynik JSON | 24 godziny po zakończeniu |
| Bulk | Manifest i wszystkie części NDJSON | 24 godziny po zakończeniu całego zadania; sprawdź expiresAt |
| YouTube Download | Dostawa JSON i media w miejscu docelowym | Dostawa JSON: zatrzymanie pracy. Media: Twój cykl życia wiadra |
| MCP pamięci podręcznej | W pełni zmontowany wynik | 10 minut; tylko cztery najnowsze duże wyniki na klucz API są zachowane |
Trzymaj mały boczny pasek zamiast
Utrzymać pierwotną odpowiedź bez zmian. Zapisz mały pasek boczny z wejściem, źródłem, zapisem czasu i używaniem, aby późniejszy proces mógł zrozumieć, co stworzył plik. Przy przekształcaniu wyników należy zachować źródło URLs i znaczniki czasu wideo.
(
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
)Zapisz bezpośrednio z HTTP
Użyj tego zamiast zapytania CLI w kroku 1. Zapisz najpierw ten sam request.json; uruchamia to nowe zapytanie używając Bash, cURL 7.76 + i jq. Ponownie użyj FLASHDATA_API_KEY i wybierz folder bez search.json. Po walidacji, te same skrypty archiwalne działają z tym wynikiem; wybierz własne zadanie ID dla --run-id.
Wyjście niezerowe cURL oznacza, że wynik nie jest gotowy do użycia. Sprawdź zapisaną odpowiedź przed ponownym uruchomieniem; czas połączenia może się zdarzyć po zaakceptowaniu zapytania. Użyj polecenia walidacji w kroku 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
)Zapisz istniejącą pracę w tle
Użyj submission.json z przewodnika async i tego samego konta. Polecenia te pobierają istniejącą pracę; nie składają kolejnego zapytania. CLI czeka na ukończenie i obsługuje redirect wyniku. Zapisz wynik w ciągu 24 godzin po zakończeniu.
(
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
)Sprawdzanie statusu kończy się, jeśli zadanie nie jest zakończone. Jeśli nadal jest w kolejce lub biegu, czekać i uruchomić ten ponownie tylko ponownie zarysować; zamiast tego sprawdzić nieudaną pracę. 302 jest pobierany bez przekazywania klucza API. Tymczasowa odpowiedź jest potwierdzana przed utworzeniem 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
)Zapisz każdą część wyniku Bulk
Zastąp BULK_ID ID w pokwitowaniu zgłoszenia. Po zakończeniu zadania, CLI następuje manifest i zapisuje każdą część jako jeden plik NDJSON. Zachowaj manifest również, gdy potrzebujesz liczenia i części metadanych.
Plik może zawierać zarówno wiersze udane, jak i nieudane. Reconcile indeksy wejściowe i liczy przed oznaczeniem całego zadania zakończone. Nie uruchamiaj ponownie całego pliku wejściowego, aby odzyskać jeden nieudany wiersz.
flashdata bulk results BULK_ID --output bulk-results.ndjson --timeout 30m --jsonZachowaj zapis dostawy i media
delivery.json zawiera zapis dostawy, a nie wideo lub bajty audio. Zapisz URL, rozmiar i suma kontrolna obok zadania. Media mieszkają w twoim magazynie docelowym i podążają za cyklem życia.
W przypadku prywatnego miejsca przeznaczenia, w celu sprawdzenia obiektu, należy użyć uwierzytelniania tego dostawcy lub podpisanego URL. Brak tymczasowego wyniku JSON nie oznacza, że Twoje przechowywane nośniki zostały usunięte.
jq '.results[] | {file_url, file_size, md5, downloaded_bytes, output_format}' delivery.jsonZmontuj kawałki MCP przed zapisaniem
Kiedy narzędzie zwraca result_id, chunk i next_offset, przeczytaj pozostałe kawałki za pomocą get_result przy użyciu tego samego klucza API. Użyj dokładnego next_offset zwróconego przez narzędzie; poniżej podane wartości są posiadaczami miejsc.
- Dołącz każdy kawałek w porządku offsetowym. Należy stosować next_offset aż do momentu, gdy będzie to null.
- Przeanalizuj dołączony tekst raz jako JSON, a następnie zapisz pełny wynik do własnego pliku lub zapisu.
- Zapisz przed expires_at. Nowe duże odpowiedzi mogą wyeksmitować starsze wyniki przed limitem 10- minute; cache przechowuje cztery na klucz API.
{
"name": "get_result",
"arguments": {
"result_id": "RESULT_ID_FROM_TOOL",
"offset": 16000
}
}Naprawiać problemy z zapisywaniem i odzyskiwaniem
| Problem | Napraw |
|---|---|
| Plik wyjściowy już istnieje | Sprawdź to najpierw. Dla zakończonego uruchomienia CLI, użyj runs show z nową nazwą pliku wyjściowego zamiast przedkładania kolejnego zapytania. |
| CLI nie może znaleźć biegu | Użyj oryginalnego katalogu użytkownika, profilu i stanu OS. Jeśli trzymasz zdalną pracę ID, odzyskaj ją bezpośrednio. |
| 401 / 403 w przypadku ponownego użycia | Uruchom flashdata auth status --json i przywróć poprawny dostęp. Lokalny plik już zapisany może być nadal odczytywany bez dostępu do API. |
| 409 / 410 | 409: czekać na istniejący zadanie. 410: użyj zapisanej kopii; tymczasowy wynik wygasł. |
| Błąd dysku po zapytania | Prowadź ID lub do zadania ID. Napraw przechowywanie i odzyskać istniejącą pracę przed rozważeniem nowego złożenia. |
| Archiwum nie ma manifestu lub suma kontrolna nie działa | Przywróć lub skopiuj ponownie oryginalne pliki. Przechowywanie niekompletnego archiwum do kontroli; odbudowa archiwum nie wymaga nowego zapytania. |
| MCP · result_unavailable | Sprawdzić wynik ID, offset, API klucz i wygaśnięcie. Użyj zapisanej kopii, jeśli pamięć podręczna wygasła; nie pętla przez powtarzanie płatnego zapytania. |