Chuyển đến nội dung
VI
Lấy khóa API
Duyệt tài liệu

Hướng dẫn

Async & Yêu cầu hàng loạt

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ưuresult.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.

Tự do truy cập và kiểm tra tài khoản
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

Chạ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.

Bash · FlashData CLI
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --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.

Bash · FlashData CLI
(
set -euC
JOB_ID=$(jq -er '.remoteId // .id // .submission.id' submission.json)
flashdata jobs wait "$JOB_ID" --timeout 2m --json
)

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.

Bash · FlashData CLI
(
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
)

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ụngChuyển đổi
Đang đợiKiê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àoMá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.
Đọc câu trả lời của địa phương là·no API cuộc gọi
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.json

Tiế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.

CLI + jq * Thu hồi công việc đã lưu
(
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.

batch.json
[
  {
    "source": "google_search",
    "query": "battery recycling research",
    "params": {
      "num": 5
    }
  },
  {
    "source": "google_search",
    "query": "lithium battery recycling methods",
    "params": {
      "num": 5
    }
  }
]
Bash · FlashData CLI
flashdata batch submit --input batch.json \
  --run-id batch-first --output batch-submission.json --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
# 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.

Bash
python3 collect-batch.py
PowerShell 7
python collect-batch.py
Đọc mỗi kết quả . jq
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json

Nhậ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ẻ.

  1. 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).
  2. 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.
  3. 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.
Yêu cầu gọi lại cho tôi
{
  "source": "google_search",
  "query": "battery recycling research",
  "params": {
    "num": 5
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Cấu hình cơ thể sự kiện
{
  "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ạngCá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 / processingTiế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.
429Honor Retry-After. Giảm bớt sự đồng thuận nếu công việc còn chờ là đầy đủ.
404 / 409404: kiểm tra ID và nộp thuế. 409: kết quả chưa sẵn sàng.
410Kế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ệcPOST https://data.flashdata.dev/v1/queries
Gửi một mẻPOST https://data.flashdata.dev/v1/queries/batch
Trạng thái đọcGET 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.

Tham số nguồ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ỉnhTải về móc, xác thực và tra cứu

Markdown á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ọ.

POSThttps://data.flashdata.dev/v1/queries
import gzip
import json
import random
import time
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"
payload = {
    "source": "google_search",
    "query": "openai",
    "params": {
        "gl": "us",
        "hl": "en",
        "num": 10,
        "page": 1,
    },
}

def api_get(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    with urllib.request.urlopen(request, timeout=60) as response:
        return json.load(response), response.headers

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, request, file_pointer, code, message, headers, new_url):
        return None

def read_result(url):
    request = urllib.request.Request(url, headers={"X-API-Key": api_key})
    try:
        with urllib.request.build_opener(NoRedirect).open(request, timeout=60):
            raise RuntimeError("Expected a result redirect")
    except urllib.error.HTTPError as response:
        if response.code != 302 or not response.headers.get("Location"):
            raise
        storage_url = response.headers["Location"]
        response.close()
    # Never forward the API key to storage.
    with urllib.request.urlopen(urllib.request.Request(storage_url, headers={"Accept-Encoding": "gzip"}), timeout=60) as response:
        content = response.read()
        if response.headers.get("Content-Encoding") == "gzip":
            content = gzip.decompress(content)
        return json.loads(content)

def link(job, relation):
    return next(item["href"] for item in job["links"] if item["rel"] == relation)

request = urllib.request.Request(
    "https://data.flashdata.dev/v1/queries",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
    headers={"Content-Type": "application/json", "X-API-Key": api_key},
    method="POST",
)
with urllib.request.urlopen(request, timeout=120) as response:
    submission = json.load(response)
jobs = submission.get("queries", [submission])
for submitted in jobs:
    print("Job:", submitted["id"])
    deadline = time.monotonic() + 300
    while time.monotonic() < deadline:
        status, headers = api_get(link(submitted, "self"))
        job = status.get("job", status)
        if job["status"] == "completed":
            result = job.get("result") if submitted["source"] == "youtube_download" and job.get("result") is not None else read_result(link(submitted, "results"))
            print(json.dumps(result, ensure_ascii=False, indent=2))
            break
        if job["status"] == "failed":
            raise RuntimeError(f"{submitted['id']}: {job.get('error', 'Job failed')}")
        hint = headers.get("Retry-After", "1")
        delay = max(1, min(5, int(hint))) if hint.isdigit() else 5
        time.sleep(min(delay * random.uniform(1, 1.2), max(0, deadline - time.monotonic())))
    else:
        raise TimeoutError(f"Still running; save this job ID: {submitted['id']}")
Hóa đơn công việc, rồi thăm dò kết quảX-API-Key Xác thực