Przeglądaj dokumentację
Poradniki
Uruchom pracę w tle dla aplikacji lub agenta, wznowić z zapisanego zadania ID i zebrać każdy wynik partii.
Na tej stronie
Kontynuuj pracę po zakończeniu procesu
Użyj pracy w tle do zadania aplikacji w kolejce lub przepływu pracy agenta, który może finish później. To przejście prowadzi jedno wyszukiwanie Google, zapisuje swój odbiór i wznawia z tego paragonu w innym procesie.
| Zachowaj | Cel |
|---|---|
| Potwierdzenie zadania | submission.json - zachowaj przyjęte zadanie ID z zadaniem aplikacji i oryginalnym wejściem. |
| Oszczędność odpowiedzi | result.json - przed importem potwierdza swoje źródło i wyniki. |
| Wyniki Batch | batch-results/outcomes.json - jeden wpis na wejście, z jego zadaniem ID i pliku rezultatu. |
Zanim zaczniesz
Użyj klawisza API z dostępem do google_search i dostępnymi kredytami. Wybierz CLI lub HTTP do składania, oczekiwania i pobierania. Przykłady Bash wykorzystują jq; HTTP potrzebuje również cURL 7.76 +. Uruchom nowy folder roboczy.
Ponownie użyj uwierzytelnionego profilu CLI lub FLASHDATA_API_KEY. Potwierdzić data.accessVerified jest true. Ustaw FLASHDATA_PROFILE na nazwany profil, więc później skrypty też go używają. Jeśli nie jest skonfigurowany żaden klucz, najpierw użyj przewodnika uwierzytelniania CLI.
flashdata auth status --json
flashdata account balance --json
flashdata account limits --jsonTrzymaj ten terminal otwarty dla pozostałych poleceń. Agenci powinni przeczytać klucz ze swojego sekretnego sklepu lub środowiska.
# 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_KEYUruchom wyszukiwanie w tle
To przejście przedstawia jeden Google Search. Sprawdzanie stanu i uzyskiwanie wyników nie powoduje kolejnego zapytania. Używaj tej samej karty kredytowej przez cały czas.
1. Prześlij raz i zachowuj pokwitowanie
Plik submission.json jest twoim pokwitowaniem. HTTP zwraca połączenia id, source, status i self/results; CLI zapisuje paragon pod złożeniem i zwraca remoteId. HTTP 200 oznacza akceptowane, nieukończone.
flashdata search "battery recycling research" --num 5 \
--mode async --run-id async-first --output submission.json --json(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e submission.json || { echo "Use the saved receipt or a new filename." >&2; exit 1; }
curl --fail-with-body --silent --show-error \
--request POST 'https://data.flashdata.dev/v1/queries' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"source":"google_search","query":"battery recycling research","params":{"num":5}}' \
--output submission.json
jq '{id, source, status, links}' submission.json
)2. Czekaj na istniejącą pracę
Kontynuuj po zakończeniu zadania. Jeśli nie powiodło się, sprawdź jego błąd przed przedłożeniem czegokolwiek innego.
Udane oczekiwanie zwraca data.status: completed w CLI JSON.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)To się sprawdza raz. Powtórzyć GET po krótkim opóźnieniu job.status jest w toku lub przetwarzania. Na 429, czekać na Retry-After od job-headers.txt.
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
STATUS_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID"
curl --fail-with-body --silent --show-error \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--max-time 30 --dump-header job-headers.txt --output job.json "$STATUS_URL"
jq -e --arg id "$JOB_ID" '.job.id == $id' job.json >/dev/null
jq '.job | {id, source, status, error}' job.json
){
"job": {
"id": "EXAMPLE_JOB_ID",
"source": "google_search",
"status": "completed",
"error": null
}
}3. Pobieranie i zapisywanie odpowiedzi
Zapisz result.json lokalnie. Wykonane zadanie i jego wynik są oddzielnymi rekordami: ciało tego wyszukiwania zawiera źródło: google_search, tablica wyników i wykorzystanie. Poniższa walidacja akceptuje zapisany wynik ukończony lub zakończony status sukcesu.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs result "$JOB_ID" --output result.json --json
jq '{source, status, results, usage}' result.json
)Domyślny wynik JSON przekierowuje się do podpisanej pamięci. Kod ten dekompresuje zapisany wynik i akceptuje również bezpośrednią odpowiedź JSON. Tylko punkt końcowy FlashData otrzymuje klucz API.
(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
JOB_ID=$(jq -er '(.remoteId // .id // .submission.id) | select(test("^[A-Za-z0-9_-]+$"))' submission.json)
SOURCE=$(jq -er '(.submission // .).source' submission.json)
jq -e --arg id "$JOB_ID" --arg source "$SOURCE" \
'.job.id == $id and .job.source == $source and .job.status == "completed"' job.json >/dev/null
test ! -e result.json || { echo "Choose a new output filename." >&2; exit 1; }
RESULT_URL="https://api.flashdata.dev/v2/jobs/$JOB_ID/results"
STATUS=$(curl --silent --show-error \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--max-time 120 --dump-header result-headers.txt --output result.pending \
--write-out '%{http_code}' "$RESULT_URL")
case "$STATUS" in
200) ;;
302)
LOCATION=$(awk 'tolower($1) == "location:" { sub(/\r$/, "", $2); print $2 }' result-headers.txt)
# The signed storage URL is fetched WITHOUT the FlashData API key.
curl --fail-with-body --silent --show-error --compressed --max-time 120 --proto '=https' \
--output result.pending "$LOCATION" ;;
*) echo "Result HTTP $STATUS; inspect 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")' result.pending >/dev/null
cat result.pending > result.json
jq '{id, source, status, results, usage}' result.json
)4. Użyj wyniku w aplikacji
Potwierdź zapisaną odpowiedź, a następnie wyodrębnij tytuł, link i wyciąć do widoku wyszukiwania lub następny krok agenta. Udane pustą tablicę organiczną oznacza brak dopasowania elementów; brakujące pole lub nieudany organ wymaga zbadania.
| Zadanie aplikacji | Przejście |
|---|---|
| Czekam | Persist przyjęte zadanie ID przed zwróceniem kontroli do użytkownika lub agenta. |
| Gotowe | Zaznacz gotowy po zapisaniu i potwierdzeniu wyniku. Użyj zadania ID jako klucza import/upsert. |
| Potrzebuje uwagi | Zachowaj zadanie ID i błąd. Czas ankietowania lub niepowodzenie wyszukiwania nie jest prośbą o ponowne złożenie. |
jq -e '.source == "google_search" and (.status == "done" or .status == "completed")
and (.results | type == "array")
and all(.results[]; (.organic | type == "array"))' result.json > /dev/null &&
jq -c '.results[] | .organic[] | {title, link, snippet}' result.jsonWznowienie w innym procesie
Otwórz świeży terminal w tym samym folderze, z tym samym credential/profile. Polecenia te odczytują zadanie w submission.json i zapisują na nową nazwę pliku. Nigdy nie przedkładają pracy. Ponowne użycie tego samego CLI run ID wymaga oryginalnego katalogu stanu; HTTP sam nie dedukuje POST przy użyciu tego lokalnego biegu ID.
(
set -eu
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs get "$JOB_ID" --json
flashdata jobs wait "$JOB_ID" --timeout 2m --json
flashdata jobs result "$JOB_ID" --output recovered-result.json --json
)Prześlij kilka zapytań
Batch przedstawia niezależne miejsca pracy w jednym wniosku. Ten przykład dwuznaczności wymaga co najmniej dwóch zapytań i dwóch oczekujących na rozpatrzenie zadań; proces tymczasowy jest ograniczony do jednego. Zapisz tablicę poniżej jako batch.json w oddzielnym folderze roboczym.
[
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
}
},
{
"source": "google_search",
"query": "lithium battery recycling methods",
"params": {
"num": 5
}
}
]flashdata batch submit --input batch.json \
--run-id batch-first --output batch-submission.json --json(
set -euC
: "${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY first}"
test ! -e batch-submission.json || { echo "Keep the saved batch receipt." >&2; exit 1; }
jq '{queries: .}' batch.json > batch-request.json
curl --fail-with-body --silent --show-error \
--request POST 'https://data.flashdata.dev/v1/queries/batch' \
--header "X-API-Key: $FLASHDATA_API_KEY" \
--header 'Content-Type: application/json' \
--data-binary @batch-request.json --output batch-submission.json
jq '.queries[] | {id, source, status}' batch-submission.json
)Zapisz collect-batch.py
Utwórz collect-batch.py w katalogu roboczym Batch obok batch.json i batch-submission.json. Skopiuj do niego cały kod poniżej i zapisz go.
Przechowywać batch.json, batch-submission.json i wyniki batch- batch / razem. Skrypt zatrzymuje się, jeśli zapisane wejścia lub paragony się zmieniają. Ponowne wykorzystanie wypełnionych plików lokalnych i nigdy nie przedstawia zamiennych zapytań po błędzie odczytu.
# collect-batch.py — Python 3.10+ and FlashData CLI; no new submissions.
import json
import re
import subprocess
import sys
from pathlib import Path
def read(path):
return json.loads(Path(path).read_text(encoding='utf-8-sig'))
def cli(*args):
result = subprocess.run(['flashdata', *args, '--json', '--non-interactive', '--timeout', '2m'],
check=True, capture_output=True, text=True, encoding='utf-8')
return json.loads(result.stdout)['data']
inputs = read('batch.json')
saved = read('batch-submission.json')
receipts = saved.get('submission', saved)['queries']
if not isinstance(inputs, list) or not inputs or len(inputs) != len(receipts):
raise ValueError('Keep the original batch input and matching receipt.')
ids = [r.get('id', '') for r in receipts]
if len(set(ids)) != len(ids) or any(not re.fullmatch(r'[A-Za-z0-9_-]+', x) for x in ids):
raise ValueError('Invalid or duplicate job IDs.')
folder = Path('batch-results')
folder.mkdir(exist_ok=True)
binding = json.dumps({'inputs': inputs, 'receipts': receipts}, sort_keys=True)
try:
with (folder / 'input-receipts.json').open('x', encoding='utf-8') as file:
file.write(binding)
except FileExistsError:
if (folder / 'input-receipts.json').read_text(encoding='utf-8') != binding:
raise ValueError('Inputs or receipts changed. Restore the original snapshot.')
outcomes = [{'index': index, 'input': request, 'job_id': receipt['id'], 'status': 'unread'}
for index, (request, receipt) in enumerate(zip(inputs, receipts))]
for index, (request, receipt) in enumerate(zip(inputs, receipts)):
job_id = receipt['id']
file = folder / (job_id + '.json')
row = {'index': index, 'input': request, 'job_id': job_id, 'status': 'unread'}
try:
if not file.exists():
try:
job = cli('jobs', 'wait', job_id)
except subprocess.CalledProcessError:
job = cli('jobs', 'get', job_id)
if job['id'] != job_id or job['source'] != request['source']:
raise ValueError('Job does not match the saved receipt/input.')
row.update(status=job['status'], error=job.get('error'))
if job['status'] == 'completed':
cli('jobs', 'result', job_id, '--output', str(file))
if file.exists():
result = read(file)
if (result.get('source') != request['source']
or result.get('status') not in ['done', 'completed']
or not isinstance(result.get('results'), list)):
raise ValueError('Inspect the saved result before importing it.')
row.update(status='completed', result_file=str(file), error=None)
except (OSError, ValueError, KeyError, subprocess.CalledProcessError) as error:
row.update(status='read_error', error=getattr(error, 'stderr', None) or str(error))
outcomes[index] = row
pending = folder / 'outcomes.next'
pending.write_text(json.dumps(outcomes, ensure_ascii=False, indent=2), encoding='utf-8')
pending.replace(folder / 'outcomes.json')
print(index, job_id, row['status'])
print('Saved batch-results/outcomes.json. No queries were submitted.')
sys.exit(0 if all(row['status'] == 'completed' for row in outcomes) else 2)Śledź każdą zaakceptowaną pracę
Po zapisaniu collect-batch.py uruchom go z folderu roboczego Batch z Python 3.10 + i uwierzytelnionym CLI. Działa z obu metod składania powyżej. Odczytuje każdy paragon, czeka do dwóch minut na niedokończoną pracę i oszczędza każdą udane odpowiedzi. Uruchom jeden kolekcjoner na raz; ponownie uruchomić go, aby kontynuować te same zadania.
Oczekuj dwóch wpisów w batch-results/outcomes.json dla próbki. Importuj zakończone wpisy według indeksu wejściowego i zadania ID. Nieudane, oczekujące i pozycje read_error pozostają widoczne; kod wyjścia 2 oznacza ich przegląd lub wznowienie. Kolekcjoner nie wysyła nowych zapytań.
python3 collect-batch.pypython collect-batch.pyjq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.jsonOtrzymuj hak dopełniający
Dodaj callback_url obok źródła, zapytania i paramów w jednym wniosku lub każdej pozycji Batch. Zamień przykład URL za pomocą odbiornika. Zdarzenia zgłaszają ukończenie lub awarię; odbierają wynik oddzielnie.
- Przećwicz wydarzenie i natychmiast zwróć 2xx. Deducplicles delivery_id (również wysłany jako X-Delivery-Id).
- Wydarzenie jest niepodpisane. Dopasuj jego identyfikator i źródło do zapisanego paragonu, a następnie uwierzytelniaj status odczytywany za pomocą łącza samego paragonu oryginalnego. Nie ufaj URLs dostarczonemu przez niezweryfikowane zdarzenie.
- Po zakończeniu, pobrać i zapisać wynik. Po nieudanej kontroli błędu pracy. Kontynuuj sondaże, jeśli nie dojdzie do żadnego wydarzenia.
{
"source": "google_search",
"query": "battery recycling research",
"params": {
"num": 5
},
"callback_url": "https://your-app.example/webhooks/flashdata"
}{
"delivery_id": "completion:EXAMPLE_JOB_ID",
"id": "EXAMPLE_JOB_ID",
"source": "google_search",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/jobs/EXAMPLE_JOB_ID",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/jobs/EXAMPLE_JOB_ID/results",
"method": "GET"
}
]
}Wymagania dotyczące Callback URL
Użyj publicznego HTTPS URL na porcie 443, co najwyżej znaków 2,048, bez uwierzytelniania lub fragmentu. Każde rozwiązane IP musi być publiczne. Omit callback_url lub użyj null lub pustego łańcucha, aby wyłączyć powiadomienia.
Odzyskanie istniejącej pracy
| Sytuacja | Co zrobić |
|---|---|
| Złożenie w wyznaczonym czasie | Sprawdź runs show async- first i konto History. runs recover może odzyskać przyjęte zadanie IDs; jeśli nie został zapisany ID, uzgodnić złożenie przed wysłaniem innego POST. |
| pending / processing | Sprawdzaj istniejącą pracę. Te stany nie są porażkami. |
| failed / 422 | Przeczytaj job.error, skorygować przyczynę i zdecydować, czy złożyć nową pracę. |
| 429 | Honor Retry-After. Ograniczenie możliwości składania wniosków w przypadku, gdy liczba miejsc pracy w trakcie składania jest pełna. |
| 404 / 409 | 404: sprawdź ID i prześlij konto. 409: wyniki nie są jeszcze gotowe. |
| 410 | Wynik przechowywania JSON wygasa 24 godziny po zakończeniu. Użyj zapisanej kopii. Media już dostarczone do Państwa magazynu są zgodne z polityką przechowywania. |
Wykonujesz zadanie YouTube Download?
Pobierz używa async lub Batch i potrzebuje właściciela klucza API z dostępem youtube_download plus miejsce przeznaczenia. Jego wynik JSON opisuje nośniki już dostarczone do wiadra; wynik końcowy nie strumieniuje bajtów wideo. Użyj przewodnika Pobierz, aby skonfigurować przechowywanie i zweryfikować dostarczony plik.
Hosts i formaty odpowiedzi
Wszystkie cztery używać X-API-Key. Użyj tego samego klucza co złożenie. Stan i wynik odczytu są darmowe, ale rate- ograniczone. Przykłady używają JSON; wybierz Accept i X-Respond-With w konstruktorze dla innych reprezentacji wyników. Podpisany pobór pamięci masowej używa URL, bez klucza FlashData.
| Działanie | Punkt końcowy |
|---|---|
| Prześlij jedną pracę | POST https://data.flashdata.dev/v1/queries |
| Prześlij partię | POST https://data.flashdata.dev/v1/queries/batch |
| Stan odczytu | GET https://api.flashdata.dev/v2/jobs/{id} |
| Przeczytaj wyniki | GET https://api.flashdata.dev/v2/jobs/{id}/results |
Obsługiwane źródła i tryby
Użyj budowniczego poniżej dla aktualnych parametrów źródła. Google Search i YouTube Data obsługują zadania w tle. YouTube Download wykorzystuje pracę w tle i miejsce przeznaczenia. Aby uzyskać duży plik wideo IDs z opcjami współdzielonymi, użyj przewodnika Bulk.
Zbuduj przepływ pracy dla swojego źródła
Wybierz źródło, edytuj jego parametry i skopiuj wygenerowany przepływ pracy w Twoim języku. Włącz wywołanie, aby ujawnić przykład odbiorcy. Ten builder podgląda kod i próbki odpowiedzi; żądania uruchamiane są tylko wtedy, gdy wykonujesz kod lub korzystasz z konsoli.
Utwórz żądanie
Parametry zaawansowane
Zaczyna się na 1. Każda strona jest odrębnym wnioskiem.
Filtr czasu Google, taki jak qdr: d za poprzedni dzień.
Dokończenie haka internetowego
Ładunek użyteczny, weryfikacja i ponowna kontrola hakaMarkdown stosuje się do zakończonych wyników. Wpływy i status pracy zachowują swoje oryginalne pola.
https://data.flashdata.dev/v1/queries