Duyệt tài liệu
Hướng dẫn
Chạy nền làm việc cho một ứng dụng hay tác nhân, tiếp tục từ công việc đã lưu của nó ID và thu thập mọi kết quả.
Trên trang này
Tiếp tục làm việc sau khi quá trình của bạn dừng lại
Dùng một công việc nền cho một tác vụ đã xếp hàng của ứng dụng hoặc một luồng tác vụ có thể finish Để sau đi. Cái này chạy được một cái. Google Tìm kiếm, lưu biên lai và tiếp tục từ hóa đơn đó trong một quá trình khác.
| Giữ | Mục đích |
|---|---|
| Biên nhận tác vụ | submission.json - giữ công việc được chấp nhận ID với tác vụ ứng dụng và nhập đầu vào gốc của bạn. |
| Đáp ứng đã lưu | result.json — xác nhận nguồn và kết quả trước khi nhập. |
| Batch Kết quả | batch-results/outcomes.json - một mục nhập vào, với công việc của nó ID và hồ sơ kết quả. |
Trước khi bắt đầu
Dùng a API phím với google_search Truy cập và tín dụng có sẵn. Chọn CLI hay HTTP để phục tùng, chờ đợi và thu hồi. Hạt Bash ví dụ dùng jq; HTTP cũng cần cURL 7.76+. Chạy trong thư mục làm việc mới.
Dùng lại xác thực của bạn CLI hồ sơ hay FLASHDATA_API_KEY. Xác nhận data.accessVerified là true. Đặt FLASHDATA_PROFILE cho một hồ sơ tên, vì vậy các tập lệnh sau này cũng sử dụng nó. Nếu không có phím được cấu hình, hãy dùng phím CLI Hướng dẫn xác thực trước.
flashdata auth status --json
flashdata account balance --json
flashdata account limits --jsonGiữ thiết bị này mở cho các lệnh còn lại. Các tác nhân nên đọc chìa khóa từ cửa hàng bí mật hay môi trường của họ.
# 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_KEYChạy tìm kiếm nền
Cái này là để đi qua một người. Google Search. Kiểm tra tình trạng và thu hồi kết quả không gửi thêm một yêu cầu nào nữa. Hãy dùng lại một cái thẻ tín dụng trong suốt.
1. Gửi một lần và giữ biên lai
Hồ sơ submission.json là biên lai của bạn. HTTP Trả lại một chứng minh thư, nguồn, tình trạng và self/results liên kết; CLI lưu biên lai dưới sự phục tùng và cũng được trả lại remoteId. HTTP 200 có nghĩa là chấp nhận, chưa hoàn thành.
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. Đợi công việc đã có
Tiếp tục khi xong việc. Nếu thất bại, hãy kiểm tra lỗi lầm trước khi nộp bất cứ thứ gì khác.
Một sự chờ đợi thành công data.status: completed in CLI JSON.
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)Đây là lần đầu tiên. Lặp lại GET sau một thời gian ngắn job.status đang chờ đợi hoặc xử lý. Vào 429Đợi đã. Retry-After từ 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. Lấy lại và giữ lại phản ứng
Cứu result.json tại địa phương. Công việc hoàn thành và cơ thể kết quả của nó là các hồ sơ riêng biệt: cơ thể tìm kiếm này chứa nguồn: google_searchMột danh sách kết quả và sử dụng. Hợp lệ hoá bên dưới chấp nhận kết quả đã được lưu hoặc hoàn thành trạng thái thành công.
(
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
)Mặc định JSON Kết quả là chuyển hướng đến kho đã ký tên. Mã này giảm bớt kết quả đã lưu và cũng chấp nhận phản ứng trực tiếp của JSON. Chỉ có FlashData Điểm cuối nhận được của bạn API Chìa khóa.
(
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. Dùng kết quả trong ứng dụng của bạn
Kiểm tra phản ứng đã lưu, rồi lấy tiêu đề, liên kết và trích đoạn để tìm kiếm hoặc bước tiếp theo của tác nhân. Một hệ thống hữu cơ trống rỗng thành công nghĩa là không có vật dụng khớp; một trường bị mất hoặc cơ thể bị thất bại cần điều tra.
| Nhiệm vụ ứng dụng | Chuyển đổi |
|---|---|
| Đang đợi | Kiên trì công việc đã nhận ID Trước khi trở lại điều khiển cho người dùng hoặc tác nhân. |
| Chào | Mác sẵn sàng sau khi kết quả được lưu và xác nhận. Dùng nhiệm vụ của bạn ID Như là import/upsert Chìa khóa. |
| Cần sự chú ý | Giữ công việc ID và lỗi. Việc bỏ phiếu quá hạn hoặc thu hồi thất bại không phải là một yêu cầu phải phục tùng lần nữa. |
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.jsonTiếp tục trong một tiến trình khác
Mở một trạm cuối mới trong cùng một thư mục, với cùng một credential/profile. Những lệnh này đọc công việc vào submission.json và lưu vào tên tập tin mới. Họ không bao giờ làm việc. Sử dụng lại cùng một CLI chạy ID yêu cầu thư mục tình trạng ban đầu của nó; HTTP bản thân nó không làm giảm hiệu quả PST bằng cách sử dụng đó chạy cục bộ 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
)Gởi vài bản tóm tắt
Batch gửi các công việc độc lập chỉ trong một yêu cầu. Ví dụ hai màn này cần có khả năng cho ít nhất hai yêu cầu và hai công việc đang chờ đợi; một thử nghiệm tạm thời chỉ là một. Lưu dãy bên dưới là batch.json trong thư mục làm việc riêng biệt.
[
{
"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
)Lưu collect-batch.py
Tạo collect-batch.py trong Batch Thư mục làm việc bên cạnh batch.json và batch-submission.json. Hãy sao chép toàn bộ mã lệnh bên dưới và lưu nó lại.
Giữ batch.json, batch-submission.json và chia nhau ra. Văn lệnh sẽ dừng nếu các dữ liệu nhập hay biên nhận thay đổi. Nó dùng lại tập tin đã hoàn thành và không bao giờ gửi các yêu cầu thay thế sau khi đọc.
# 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)Theo dõi mỗi công việc đã nhận
Sau khi lưu collect-batch.pyChạy nó khỏi Batch thư mục làm việc với Python 3.10+ và xác thực CLI. Nó hoạt động với phương pháp phục tùng ở trên. Nó đọc mọi biên lai, đợi đến hai phút cho mỗi lần làm việc chưa hoàn thành và tiết kiệm được mỗi phản hồi thành công. Điều hành từng nhà sưu tập một; chiếu lại nó để tiếp tục công việc cũ.
Mong đợi hai mục nhập vào batch-results/outcomes.json cho mẫu thử. Nhập xong mục nhập theo chỉ mục và công việc nhập ID. Thất bại, chờ đợi và read_error Mục còn lại hiển thị; mã thoát 2 có nghĩa là xem xét hoặc tiếp tục chúng. Người thu thập không gửi thư mới.
python3 collect-batch.pypython collect-batch.pyjq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.jsonNhận một trình điều khiển hoàn tất
Thêm callback_url bên cạnh nguồn, truy vấn và tham số trong một yêu cầu hoặc mỗi Batch vào. Thay thế mẫu URL với bộ nhận tín hiệu. Các sự kiện báo cáo hoàn tất hoặc thất bại; lấy kết quả riêng lẻ.
- Hãy tiếp tục sự kiện và trả lại nhanh 2x. Chất nhuộm delivery_id (cũng gửi như vậy X-Delivery-Id).
- Sự kiện này không được ký kết. Khớp ID của nó và nguồn cho biên nhận đã lưu của bạn, sau đó xác thực một trạng thái đọc bằng cách sử dụng liên kết gốc của tự biên nhận. Không được tin tưởng URLs cung cấp bởi một sự kiện không xác định.
- Khi hoàn thành, hãy lấy và lưu lại kết quả. Khi thất bại, hãy kiểm tra lỗi công việc. Cứ tiếp tục bỏ phiếu như một hậu quả nếu không có sự kiện nào đến.
{
"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"
}
]
}Yêu cầu gọi ngược URL
Dùng công chúng HTTPS URL trên cổng 443, ít nhất 2,048 các nhân vật, không có giấy ủy nhiệm hoặc một mảnh ghép. Mỗi IP được giải quyết phải được công bố. Omit callback_urlhoặc dùng null hoặc chuỗi rỗng, để tắt thông báo.
Phục hồi một công việc đã có
| Tình trạng | Cách xử lý |
|---|---|
| Đã quá giờ | Kiểm tra runs show một tài khoản và đặc trưng History. runs recover có thể lấy lại công việc đã nhận IDs; nếu không ID đã được cứu, hòa giải sự phục tùng trước khi gửi một cái khác POST. |
| pending / processing | Tiếp tục kiểm tra công việc đã có. Những bang này không thất bại. |
| failed / 422 | Đọc job.error, chỉnh lại nguyên nhân và quyết định có nên nộp tác phẩm mới hay không. |
| 429 | Honor Retry-After. Giảm bớt sự đồng thuận nếu công việc còn chờ là đầy đủ. |
| 404 / 409 | 404: kiểm tra ID và nộp thuế. 409: kết quả chưa sẵn sàng. |
| 410 | Kết quả đã lưu JSON Hết hạn 24 hàng giờ sau khi hoàn thành. Dùng bản sao lưu của anh đi. Truyền thông đã chuyển đến kho lưu trữ của bạn theo chính sách lưu trữ đó. |
Chạy một YouTube Download Công việc?
Tải về sử dụng định kỳ hoặc Batch và cần một chủ nhân API phím với youtube_download Truy cập cộng với nơi lưu trữ. Kết quả JSON Mô tả phương tiện truyền thông đã được chuyển đến xô của bạn; kết quả là điểm kết thúc không truyền tải video byte. Dùng hướng dẫn tải về để cấu hình khả năng lưu trữ và kiểm tra tập tin đã gửi.
Máy và định dạng trả lời
Tất cả đều dùng X-API-Key. Dùng cùng chìa khóa để phục tùng. Tình trạng và kết quả là miễn phí, nhưng giới hạn theo tỷ lệ. Những ví dụ được sử dụng JSON; chọn Accept và X-Respond-With trong việc xây dựng cho những kết quả khác. Name URLkhông có FlashData Chìa khóa.
| Thao tác | Điểm kết thúc |
|---|---|
| Nhận một việc | POST https://data.flashdata.dev/v1/queries |
| Gửi một mẻ | POST https://data.flashdata.dev/v1/queries/batch |
| Trạng thái đọc | GET https://api.flashdata.dev/v2/jobs/{id} |
| Đọc kết quả | GET https://api.flashdata.dev/v2/jobs/{id}/results |
Các nguồn và chế độ đã hỗ trợ
Sử dụng người xây dựng bên dưới cho các thông số hiện tại của nguồn. Google Search và YouTube Data hỗ trợ công việc nền. YouTube Download sử dụng các công việc nền và lưu trữ điểm đến. Đối với một tập tin lớn của video IDs với các tùy chọn được chia sẻ, sử dụng Bulk Hướng dẫn viên.
Xây dựng dòng chảy công việc cho nguồn của bạn
Chọn một nguồn, chỉnh sửa tham số và sao chép luồng công việc tạo ra trong ngôn ngữ của bạn. Bật gọi lại để hiển thị ví dụ bộ nhận. Ô xem thử cấu hình này hiển thị mã và đáp ứng mẫu; yêu cầu chạy chỉ khi bạn thực hiện mã hoặc dùng bàn điều khiển.
Tạo yêu cầu
Tham số nâng cao
Bắt đầu ở 1. Mỗi trang là một yêu cầu riêng biệt.
Google lọc thời gian, như qdr:d cho ngày qua.
Bổ sung hoàn chỉnh
Tải về móc, xác thực và tra cứuMarkdown áp dụng cho kết quả hoàn tất. Hóa đơn và địa vị công việc giữ những cánh đồng nguyên thủy của họ.
https://data.flashdata.dev/v1/queries