본문으로 건너뛰기
KO
API 키 받기
문서 둘러보기

가이드

Async 및 일괄 요청

응용 프로그램 또는 에이전트에 대 한 배경 작업을 실행, 그것의 저장된 작업 ID에서 이력서 및 모든 배치 결과 수집.

이 페이지의 내용

프로세스가 중지한 후 계속 작업

나중에 finish를 사용할 수 있는 쿼츠 애플리케이션 작업 또는 에이전트 워크플로우에 대한 배경 작업을 사용합니다. 이 walkthrough는 하나의 Google 검색을 실행하고 영수증을 저장하고 다른 과정에서 그 영수증에서 이력서를 저장합니다.

보관제품정보
작업 접수 정보submission.json - 응용 프로그램 작업과 원본 입력으로 허용되는 작업 ID를 유지합니다.
저장된 응답result.json - 소스를 검증하고 결과를 가져 오기 전에 검증합니다.
Batch 결과batch-results/outcomes.json - 입력 당 한 항목, 작업 ID 및 결과 파일.

시작하기 전에

API 키와 google_search 액세스 및 사용 가능한 크레딧을 사용하십시오. CLI 또는 HTTP를 선택하여 제출, 대기 및 검색을 선택하십시오. Bash 예제는 jq를 사용합니다. HTTP는 또한 cURL 7.76+를 필요로 합니다. 새 작업 폴더에서 실행.

인증된 CLI 프로파일 또는 FLASHDATA_API_KEY를 재사용하십시오. data.accessVerified는 true입니다. FLASHDATA_PROFILE 를 설정하여 나중에 스크립트를 사용하므로 이름을 지정합니다. 키가 구성되지 않으면 CLI 인증 가이드를 먼저 사용하십시오.

무료 액세스 및 계정 확인
flashdata auth status --json
flashdata account balance --json
flashdata account limits --json

배경 검색 실행

이 연습은 Google Search를 제출합니다. 상태 확인 및 결과 검색은 다른 쿼리를 제출하지 않습니다. 전반적으로 동일한 자격 증명을 재사용합니다.

1. 한 번 제출하고 영수증을 보관하십시오

submission.json 파일은 영수증입니다. HTTP는 id, 소스, 상태 및 self/results 링크를 반환합니다; CLI는 제출하에 영수증을 저장하고 remoteId를 반환합니다. HTTP 200는, 완성되지 않습니다 받아들여집니다.

Bash · FlashData CLI
flashdata search "battery recycling research" --num 5 \
  --mode async --run-id async-first --output submission.json --json

2. 현재 업무에 대한 기대

작업이 완료되면 계속됩니다. 실패한 경우, 다른 것을 제출하기 전에 오류를 검사합니다.

성공적인 대기 반환 data.status: completed 으로 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. 응답을 검색하고 저장

result.json를 로컬로 저장합니다. 완료된 작업과 그 결과 몸은 별도의 레코드입니다: 이 검색의 신체는 소스가 포함되어 있습니다: google_search, 결과 배열 및 사용. 아래의 유효성 검사는 저장된 결과의 완료 또는 완료된 성공 상태를 허용합니다.

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. 당신의 신청에 있는 결과를 사용하십시오

저장된 응답을 검증하고, 검색보기 또는 에이전트의 다음 단계를 위해 제목, 링크 및 스니펫을 추출합니다. 성공적인 빈 유기 배열은 일치하는 품목을 의미하지 않습니다; 누락된 분야 또는 실패한 몸은 조사를 필요로 합니다.

적용 작업관련 기사
을 읽다Persist는 사용자 또는 대리인에 통제를 돌려보내기 전에 받아들여진 일 ID를 주장합니다.
지원하다결과가 저장되고 검증된 후 Mark가 준비되었습니다. import/upsert 키로 작업 ID를 사용하십시오.
자주 묻는 질문ID 및 오류를 유지하십시오. 퇴직시간 또는 퇴직시간은 다시 제출할 수 없습니다.
로컬 응답 읽기 · API 통화 없음
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

다른 과정에 이력서

같은 폴더에 신선한 터미널을 열고, 같은 credential/profile. 이 명령은 submission.json에서 작업을 읽고 새 파일명에 저장합니다. 그들은 결코 일을 제출하지 않습니다. 동일한 CLI 실행을 재사용 ID는 원래 상태 디렉토리를 요구합니다; HTTP 자체는 로컬 실행 ID를 사용하여 POST를 deduplicate하지 않습니다.

CLI + jq · 저장된 작업을 복구
(
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
)

여러 쿼리 제출

Batch는 하나의 요청에 독립적 인 작업을 제출합니다. 이 두 가지 예는 적어도 두 개의 쿼리와 두 개의 보류 작업에 대한 용량을 필요로합니다. 임시 체험은 하나에 제한됩니다. 별도의 작업 폴더에서 batch.json로 아래 배열을 저장하십시오.

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

저장 collect-batch.py

batch.json와 batch-submission.json 옆에 Batch 작업 폴더에 collect-batch.py를 만듭니다. 아래의 전체 코드를 복사하고 저장합니다.

batch.json, batch-submission.json 및 일괄 용량을 함께 유지하십시오. 저장된 입력 또는 영수증이 변경되면 스크립트가 중지됩니다. 로컬 파일을 재사용하고 읽기 오류 후 대체 쿼리를 제출하지 마십시오.

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)

각 취업을 추적

collect-batch.py 저장 후 Python 3.10+와 정통 CLI를 가진 Batch 작업 폴더에서 실행하십시오. 위의 제출 방법 중 하나와 함께 작동합니다. 그것은 모든 영수증을 읽고, 불완전한 일 당 2 분까지 기다리고 각 성공적인 응답을 저장합니다. 한 명의 수집가를 한 번에 실행하십시오. 동일한 작업을 계속하려면 다시 실행하십시오.

샘플에 대한 batch-results/outcomes.json에서 두 항목이 기대됩니다. 입력 인덱스 및 작업 ID에 의해 완료된 항목 가져 오기. 실패, 종료 및 read_error 항목이 눈에 띄지 않습니다. 종료 코드 2는 검토 또는 이력서를 의미합니다. 수집가는 새로운 쿼리를 보냅니다.

Bash
python3 collect-batch.py
PowerShell 7
python collect-batch.py
각 결과를 읽으십시오 · jq
jq '.[] | {index, job_id, status, result_file, error}' batch-results/outcomes.json

웹훅을 완료

callback_url를 소스 옆에 추가, 쿼리 및 단일 요청 또는 각 Batch 항목에 params. 수신기를 가진 예 URL를 대체하십시오. 이벤트 보고서 완료 또는 실패; 결과를 개별적으로 검색합니다.

  1. 이벤트를 감독하고 2xx를 신속하게 반환합니다. delivery_id (또한 X-Delivery-Id로 보내)를 분해하십시오.
  2. 이벤트가 취소되지 않습니다. 저장된 영수증에 그것의 ID와 근원 일치하고, 그 후에 본래 영수증의 각자 연결을 사용하여 읽는 상태를 정정합니다. URLs를 믿을 수 없습니다.
  3. 완료되면 fetch를 저장하고 결과를 저장합니다. 실패한 경우, 작업 오류를 검사합니다. 이벤트가 도착하지 않으면 가을으로 오염을 지키십시오.
콜백을 가진 몸 요청
{
  "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"
    }
  ]
}

Callback URL 요구 사항

포트 443에 HTTPS URL, 대부분의 2,048 문자에서, credentials 또는 파편없이. 모든 해결된 IP는 공개해야 합니다. Omit callback_url 또는 null 또는 빈 문자열을 사용하여 알림을 비활성화합니다.

기존의 작업을 복구

- 연혁해결 방법
제출 시간runs show async-first 및 계정 History를 검사하십시오. runs recover는 IDs를 받아들일 수 있습니다; ID가 저장되지 않은 경우에, 다른 POST를 보내기 전에 제출을 재구성하십시오.
pending / processing기존의 작업을 계속하십시오. 이 상태는 실패하지 않습니다.
failed / 422job.error를 읽고, 원인을 수정하고 새로운 작업을 제출 여부를 결정하십시오.
429명예 Retry-After. pending-job 용량이 가득하다면 제출 concurrency를 줄입니다.
404 / 409404: ID를 확인하고 계정을 제출하십시오. 409: 결과는 아직 준비되어 있지 않습니다.
410저장된 결과 JSON는 24 시간을 완료한 후 만료됩니다. 저장된 사본을 사용하십시오. 미디어는 이미 저장에 전달되어 저장의 보존 정책을 따르고 있습니다.

YouTube Download 작업 실행?

다운로드는 동기화 또는 Batch를 사용하고 youtube_download 액세스 플러스 대상 저장과 소유자 API 키가 필요합니다. 그 결과 JSON는 미디어가 이미 양동이에 전달되었습니다. 결과 엔드포인트는 비디오 바이트를 스트리밍하지 않습니다. 다운로드 가이드를 사용하여 저장을 구성하고 전달된 파일을 확인합니다.

호스트 및 응답 형식

모든 4 사용 X-API-Key. 제출과 동일한 키를 사용합니다. 상태와 결과 읽기는 무료입니다, 하지만 속도 제한. 예제는 JSON를 사용합니다. Accept 및 X-Respond-With를 다른 결과 표현에 대한 빌더로 선택하십시오. 서명된 저장 다운로드는 그것을 사용합니다 URL, 없이 FlashData 주요.

- 연혁끝점
1개의 일자리를 제출POST https://data.flashdata.dev/v1/queries
일괄 제출POST https://data.flashdata.dev/v1/queries/batch
읽음 상태GET https://api.flashdata.dev/v2/jobs/{id}
결과 읽기GET https://api.flashdata.dev/v2/jobs/{id}/results

지원된 소스 및 모드

소스의 현재 매개 변수에 대한 아래 빌더를 사용합니다. Google Search 및 YouTube Data 지원 배경 작업. YouTube Download는 배경 작업 및 목적지 저장을 사용합니다. 공유 옵션이있는 비디오 IDs의 큰 파일에 대해서는 Bulk 가이드를 사용하십시오.

소스에 대한 작업 흐름을 구축

소스를 선택하고 매개 변수를 편집하고 언어의 생성 된 워크플로를 복사합니다. 수신자 예를 공개하기 위해 콜백을 활성화하십시오. 이 빌더 미리보기 코드 및 샘플 응답; 요청은 코드를 실행하거나 콘솔을 사용합니다.

소스 매개 변수

요청 구성

고급 매개변수

1에서 시작합니다. 각 페이지는 별도의 요청입니다.

qdr:d와 같은 Google 시간 여과기 과거를 위해.

웹훅Webhook 페이로드, 검증 및 재량

Markdown는 완료된 결과에 적용합니다. 영수증 및 작업 상태는 원래 필드를 유지합니다.

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']}")
작업 영수증, 그 결과에 대한 설문 조사X-API-Key 인증