تصفح الوثائق
مرجع API
أنشئ مهام YouTube القائمة على الملفات وتحكّم فيها، ثم استرجع ملفات البيان وأجزاء النتائج.
في هذه الصفحة
بيئة تجربة API
(ب) اختيار مصدر ونسخ كامل لتدفق العمل من طراز Python أو Bash، أو طلب واحد، أو رد العينة. الملعب يُفترض أنه لا يقدم عملاً وتعالج تدفقات العمل الكاملة عبء التحميل، والتحقق من الوضع، واسترجاع كل جزء من أجزاء النتائج.
بناء تدفق عمل من طراز Bulk
ملف محلي بصيغة UTF-8، بمعرّف YouTube واحد في كل سطر، وبحجم يصل إلى 2 GiB. الاحتياجات من المدخلات.
تسليم النتائج
اترك هذا لاسترجاع النتائج من خلال FlashData API.
موقع استكمال Bulk على شبكة الإنترنت(ح)
الإخطارات المتعلقة بإكمال المهام والتحقق منهاhttps://api.flashdata.dev/v2/bulk-jobsنقاط النهاية
جميع نقاط النهاية تستخدم https://api.flashdata.dev/v2. اصنعي وظيفة احملي شريط فيديوID ابدأوا بالمراقبة و استرجعوا البيانات وكل جزء من النتائج
| المنهجية | Path | الإجراء |
|---|---|---|
| POST | /v2/bulk-jobs | إنشاء وظيفة من طراز Bulk |
| POST | /v2/bulk-jobs/{bulkId}/start | تحميل وبدء |
| GET | /v2/bulk-jobs/{bulkId} | الحصول على وظيفة |
| GET | /v2/bulk-jobs | الوظائف المدرجة في القائمة |
| POST | /v2/bulk-jobs/{bulkId}/pause | اوقفوا العمل |
| PATCH | /v2/bulk-jobs/{bulkId} | تحديث خيارات العمل |
| POST | /v2/bulk-jobs/{bulkId}/resume | إستئناف وظيفة |
| DELETE | /v2/bulk-jobs/{bulkId} | إلغاء وظيفة |
| GET | /v2/bulk-jobs/{bulkId}/results | احصل على نتائج |
| GET | /v2/bulk-jobs/{bulkId}/results/{partNumber} | قطع الغيار |
التوثيق والمدخلات
اضبط FLASHDATA_API_KEY على مفتاح يملك صلاحية المصدر المختار. أعد استخدام المفتاح والحساب نفسيهما للإنشاء والتحكم والنتائج. تستخدم المعالجة رصيد الحساب وأسعار المصدر المعتادة. يتطلب YouTube Download وصول المالك وoptions.storage.
إنشاء ملف عمل اسمه " السوائب " وطرح هذه الأمثلة منه. اكتملت ساحة اللعب Python استخدامات تدفق العمل Python 3.10+ المكتبة الموحدة؛ الفرد Python وتحتاج الأمثلة النهائية الواردة أدناه إلى طلبات؛ cURL أمثلة Bash, cURL 7.76+, jq و(زب) اختر لغة واحدة لكل عمل حتى لا تخلق أو تبدأ العمل المزدوج
المدخلات هي: UTF-8 ملف واحد 11-منتج YouTube ID لكل خط 2 جي بي. الاستخدام IDsليس URLs. Remove duplicate IDs before uploading; repeated IDs are processed separately.
| المصدر | الخيارات المشتركة |
|---|---|
| youtube_metadata | include_formats, include_chapters |
| youtube_transcript | اللغة الآلية |
| youtube_captions | اللغة الآلية |
| youtube_trainability | لا خيارات |
| youtube_download | خيارات وسائط الإعلام ومقصد التخزين |
python -m pip install requestsإنشاء حقول طلب
| الميدان | النوع | Usage |
|---|---|---|
| source | string | مطلوب. دعم مصدر لكل مدخلات ID. |
| options | object | خيارات المصادر المشتركة. ويمكن أن تحدد مصادر البيانات موقع result_storage؛ YouTube Download يَحتاجُ للتخزين. |
| callback_url | string | الرأي العام HTTPS إستعادة إستدعاء. Sent after manifest publication. |
إنشاء وظيفة من طراز Bulk
إنشاء وظيفة، وتحميل ملف نصي من طراز UTF-8 مع ملصق من طراز 11-character YouTube شريط فيديو ID لكل خط إلى upload.href، ثم الاتصال بالبدء. إن إنشاء الوظيفة وحدها لا يبدأ في التجهيز.
ويكتب هذا المثال video-ids.txt ويحتفظ باستلام 201 إلى bulk-created.json. أبقي هذا الإيصال خاصًا وأعيد استخدامه job.id لكل طلب لاحق إنشاء وظيفة يتركها في awaiting_upload; the upload URL تنتهي مدة العضوية بعد 15 دقائق.
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYوفّر bulk_create.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
os.umask(0o077)
Path("video-ids.txt").write_bytes(b"jNQXAC9IVRw\ndQw4w9WgXcQ\n")
response = requests.post(
"https://api.flashdata.dev/v2/bulk-jobs",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
json={"source": "youtube_metadata", "options": {"include_formats": False}},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
receipt = response.json()
Path("bulk-created.json").write_text(json.dumps(receipt, indent=2), encoding="utf-8")
print(json.dumps(receipt["job"], indent=2))python bulk_create.pyumask 077
printf '%s\n' 'jNQXAC9IVRw' 'dQw4w9WgXcQ' > video-ids.txt
curl --fail-with-body --silent --show-error \
'https://api.flashdata.dev/v2/bulk-jobs' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' \
--data '{"source":"youtube_metadata","options":{"include_formats":false}}' \
--output bulk-created.json &&
jq '.job | {id, source, status}' bulk-created.jsonالردود والطلب
| HTTP | معنى |
|---|---|
| 201 | Bulk created with a 15-minute direct upload URL |
| 401 | التوثيق المطلوب أو غير صحيح |
| 422 | فشل التثبت من الطلب |
| 503 | التبعية المطلوبة أو المكتال غير متاح بصورة مؤقتة |
{
"$ref": "#/components/schemas/CreateBulkJobRequest"
}{
"$ref": "#/components/schemas/BulkJobCreated"
}تحميل وبدء
ابدأوا بتجهيز الحمولة UTF-8 فيديو ID الملف، حتى 2 غيبي2147483648 (ب) أبقِ الملفَ بدون تغيير بعد البَدْء.
أولا PUT video-ids.txt إلى الإيصال upload.href مع upload.contentTypeبدون X-API-Key. على سبيل المثال لا تبدأ إلا بعد أن ينجح تحميلها. أبقوا الملف المُحمّل بدون تغيير بعد ذلك.
| البارامترات | الموقع | الاحتياج |
|---|---|---|
| bulkId | path | مطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEYوفّر bulk_start.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
receipt = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))
upload = receipt["upload"]
if upload["method"] != "PUT" or not upload["href"].startswith("https://"):
raise ValueError("Expected an HTTPS PUT upload URL")
# Stream the file to storage without the FlashData key.
with open("video-ids.txt", "rb") as file:
response = requests.put(
upload["href"], data=file,
headers={"Content-Type": upload["contentType"]},
timeout=300, allow_redirects=False,
)
response.raise_for_status()
if not 200 <= response.status_code < 300:
raise RuntimeError("Upload did not complete; do not start the job yet")
bulk_id = receipt["job"]["id"]
response = requests.post(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/start",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json()["job"], indent=2))python bulk_start.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
UPLOAD_URL=$(jq -er '.upload.href' bulk-created.json)
CONTENT_TYPE=$(jq -er '.upload.contentType' bulk-created.json)
curl --fail-with-body --silent --show-error --proto '=https' \
--header "Content-Type: $CONTENT_TYPE" \
--upload-file video-ids.txt "$UPLOAD_URL" &&
curl --fail-with-body --silent --show-error --request POST \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/start" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}"الردود
| HTTP | معنى |
|---|---|
| 200 | بدأت وظيفة Bulk أو حالتها الحالية |
| 401 | التوثيق المطلوب أو غير صحيح |
| 404 | الموارد التي لم يعثر عليها أو لا يملكها المتصل |
| 409 | النزاع في حالة الموارد أو الافتراض |
| 422 | فشل التثبت من الطلب |
| 503 | التبعية المطلوبة أو المكتال غير متاح بصورة مؤقتة |
{
"$ref": "#/components/schemas/BulkJobResponse"
}الحصول على وظيفة
اقرأ job.status وinput وcounts وpauseReason وerror. أعد فحص المعرّف نفسه بعد انتظار؛ وتعني completed نشر manifest، لا نجاح كل فيديو.
| البارامترات | الموقع | الاحتياج |
|---|---|---|
| bulkId | path | مطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYوفّر bulk_status.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("bulk-job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))python bulk_status.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output bulk-job.json &&
jq '.job | {id, status, counts, pauseReason, error, expiresAt}' bulk-job.jsonالردود
| HTTP | معنى |
|---|---|
| 200 | Bulk وظيفة ولاية |
| 401 | التوثيق المطلوب أو غير صحيح |
| 404 | الموارد التي لم يعثر عليها أو لا يملكها المتصل |
{
"$ref": "#/components/schemas/BulkJobResponse"
}الوظائف المدرجة في القائمة
ويتضمن الرد بيانات ومهرجات. مرّة pagination.nextCursor كبرامتر إستفسار الطلب التالي حتى هو null. (ج) الحد الأقصى للاستخدام من 1 إلى 50؛ والمقدار هو 20.
| البارامترات | الموقع | الاحتياج |
|---|---|---|
| cursor | query | اختياري · {"type":"string","maxLength":512} |
| limit | query | اختياري · {"type":"integer","minimum":1,"maximum":50,"default":20} |
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEYوفّر list_bulk_jobs.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
response = requests.get(
"https://api.flashdata.dev/v2/bulk-jobs?limit=20",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python list_bulk_jobs.pycurl --fail-with-body --silent --show-error --max-time 30 \
--request GET \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs?limit=20"الردود
| HTTP | معنى |
|---|---|
| 200 | Bulk Page |
| 401 | التوثيق المطلوب أو غير صحيح |
{
"$ref": "#/components/schemas/BulkJobPage"
}اوقفوا العمل
وقف العروض الجديدة وتعبئة النتائج. وتستمر الوظائف القائمة بأماكنها الأصلية واتهامها. إسترجعْ العملَ عندما يَستعدُّ.
| البارامترات | الموقع | الاحتياج |
|---|---|---|
| bulkId | path | مطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEYوفّر pause_bulk_job.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/pause",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python pause_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request POST \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/pause"الردود
| HTTP | معنى |
|---|---|
| 200 | وظيفة بالجملة مدفوعة الأجر أو الدولة الافتراضية الحالية |
| 401 | التوثيق المطلوب أو غير صحيح |
| 404 | الموارد التي لم يعثر عليها أو لا يملكها المتصل |
{
"$ref": "#/components/schemas/BulkJobResponse"
}تحديث خيارات العمل
تحديث الخيارات في انتظار تحميلها، أو مع تمهيدها قبل قراءة جميع المدخلات. الوظائف الموجودة تحتفظ بأماكنها إذا كان التوقف لا يزال جارياً، فانتظر وأعيد فحص ردّ شركة 409. وبعد قراءة جميع المدخلات، لا يمكن تحديث سوى وثائق تفويض التسليم. المجموعة callback_url إلى null لإزالته.
وهذا المثال يزيل عودتي الاستكمال. ولتغيير خيارات المصدر، أرسلوا بدلاً من ذلك موضوعاً للخيارات. وقف أولاً وانتظر أن يبدأ نفاذ الوقف؛ يعني الرقم 409 أنه لا يمكن بعد تطبيق آخر المستجدات. وظائف الأطفال القائمة تحتفظ بخياراتهم الأصلية.
| البارامترات | الموقع | الاحتياج |
|---|---|---|
| bulkId | path | مطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYوفّر update_bulk_job.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.patch(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
json={"callback_url": None},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python update_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request PATCH \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Content-Type: application/json' --data '{"callback_url":null}' \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID"الردود والطلب
| HTTP | معنى |
|---|---|
| 200 | آخر وظيفة في حالة السوائب |
| 401 | التوثيق المطلوب أو غير صحيح |
| 404 | الموارد التي لم يعثر عليها أو لا يملكها المتصل |
| 409 | النزاع في حالة الموارد أو الافتراض |
| 422 | فشل التثبت من الطلب |
{
"$ref": "#/components/schemas/UpdateBulkJobRequest"
}{
"$ref": "#/components/schemas/BulkJobResponse"
}إستئناف وظيفة
استأنفت شركة pauseReason أولاً، مثل إضافة ائتمانات أو تحديث وثائق التفويض في التخزين، ثم استأنفت نفس الرقم Bulk ID.
| البارامترات | الموقع | الاحتياج |
|---|---|---|
| bulkId | path | مطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEYوفّر resume_bulk_job.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/resume",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python resume_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request POST \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/resume"الردود
| HTTP | معنى |
|---|---|
| 200 | الوظيفة العامة الحالية |
| 401 | التوثيق المطلوب أو غير صحيح |
| 404 | الموارد التي لم يعثر عليها أو لا يملكها المتصل |
{
"$ref": "#/components/schemas/BulkJobResponse"
}إلغاء وظيفة
وقف تقديم عروض جديدة. الوظائف الحالية يمكن أن تظل finish و تُوجّه إليهم تهمهم العادية ولا تنشر الوظيفة الملغاة بيانا نهائيا.
| البارامترات | الموقع | الاحتياج |
|---|---|---|
| bulkId | path | مطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEYوفّر cancel_bulk_job.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.delete(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))python cancel_bulk_job.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
curl --fail-with-body --silent --show-error --max-time 30 \
--request DELETE \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID"الردود
| HTTP | معنى |
|---|---|
| 200 | الوظيفة العامة الحالية |
| 401 | التوثيق المطلوب أو غير صحيح |
| 404 | الموارد التي لم يعثر عليها أو لا يملكها المتصل |
{
"$ref": "#/components/schemas/BulkJobResponse"
}احصل على نتائج
(أ) تتبع إعادة توجيه عملية تحميل بيان JSON، وتستخدم صلاتها باسترجاع ملفات النتائج. ووقعت فيتش على مخزن URLs بدون مفتاح API. لا تزال النتائج متاحة 24 بعد ساعات من كامل Bulk العمل يكتمل.
The authenticated API request returns 302 with a Location header. (أ) أن تخزن شركة HTTPS URL في طلب منفصل بدون X-API-Key. المثال ينقذ manifest.json. A 409 means results are not ready; 410 means they expired.
| البارامترات | الموقع | الاحتياج |
|---|---|---|
| bulkId | path | مطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEYوفّر bulk_manifest.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
raise RuntimeError(f"Expected a manifest redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
raise ValueError("Expected an HTTPS storage URL")
manifest = requests.get(url, timeout=120) # No FlashData API key.
manifest.raise_for_status()
Path("manifest.json").write_text(json.dumps(manifest.json(), indent=2), encoding="utf-8")
print(json.dumps(manifest.json(), indent=2))python bulk_manifest.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
# Only send the API key to FlashData; fetch storage URLs separately.
fetch_bulk_result() {
local storage_url
storage_url=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/results$1" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') || return
curl --fail-with-body --silent --show-error --proto '=https' \
"${storage_url:?Expected a signed result URL}" --output "$2"
}
fetch_bulk_result '' manifest.json &&
jq '{status, counts, parts, expires_at}' manifest.jsonالردود
| HTTP | معنى |
|---|---|
| 200 | ملف بيان JSON يُنزَّل بعد اتباع إعادة التوجيه |
| 302 | إعادة توجيه إلى رابط R2 خاص قصير الصلاحية؛ يجب عدم تمرير بيانات اعتماد API إليه · Location |
| 401 | التوثيق المطلوب أو غير صحيح |
| 404 | الموارد التي لم يعثر عليها أو لا يملكها المتصل |
| 409 | النزاع في حالة الموارد أو الافتراض |
| 410 | انتهت صلاحية النتيجة المحتفظ بها |
{
"type": "object",
"additionalProperties": true
}قطع الغيار
استخدام كل واحد parts[].number من manifest.json. وتعيد كل نقطة نهاية ملف 302 إلى ملف Gzip NDJSON؛ والتنزيل بدون مفتاح API، و decompress، ثم برد واحد من الجسم JSON لكل خط. انضم إلى الرقم القياسي الصفري. المثال يستعيد كل الأجزاء ويحتفظ بكلاهماndjson.gz وملفات (أندجون)
| البارامترات | الموقع | الاحتياج |
|---|---|---|
| bulkId | path | مطلوب · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"} |
| partNumber | path | مطلوب · {"type":"integer","minimum":0} |
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEYوفّر bulk_parts.py in bulk-api/ beside bulk-created.json. عُلم النص الكامل ثمّ أدير القيادة تحته
import json
import os
from pathlib import Path
import requests
import gzip
import shutil
bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
manifest = json.loads(Path("manifest.json").read_text(encoding="utf-8"))
for part in manifest["parts"]:
number = part["number"]
response = requests.get(
f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results/{number}",
headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
raise RuntimeError(f"Expected a part redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
raise ValueError("Expected an HTTPS storage URL")
# Save the original gzip bytes; do not decompress twice.
with requests.get(url, stream=True, timeout=120) as download:
download.raise_for_status()
with open(f"part-{number}.ndjson.gz", "wb") as file:
download.raw.decode_content = False
shutil.copyfileobj(download.raw, file)
with gzip.open(f"part-{number}.ndjson.gz", "rt", encoding="utf-8") as rows:
with open(f"part-{number}.ndjson", "w", encoding="utf-8") as file:
for line in rows:
file.write(line)
print(json.dumps(json.loads(line)))python bulk_parts.pyBULK_ID=$(jq -er '.job.id' bulk-created.json)
# Only send the API key to FlashData; fetch storage URLs separately.
fetch_bulk_result() {
local storage_url
storage_url=$(curl --fail-with-body --silent --show-error \
"https://api.flashdata.dev/v2/bulk-jobs/$BULK_ID/results$1" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--output /dev/null --write-out '%{redirect_url}') || return
curl --fail-with-body --silent --show-error --proto '=https' \
"${storage_url:?Expected a signed result URL}" --output "$2"
}
fetch_bulk_result '' manifest.json &&
jq '{status, counts, parts, expires_at}' manifest.json
# Run in the same Bash session as fetch_bulk_result.
jq -r '.parts[].number' manifest.json | while IFS= read -r PART; do
fetch_bulk_result "/$PART" "part-$PART.ndjson.gz" || exit
gzip -dc "part-$PART.ndjson.gz" > "part-$PART.ndjson" || exit
jq -c '{index, video_id, status, results, error}' "part-$PART.ndjson"
doneالردود
| HTTP | معنى |
|---|---|
| 200 | ملف NDJSON مضغوط باستخدام Gzip يُنزَّل بعد اتباع إعادة التوجيه |
| 302 | إعادة توجيه إلى رابط R2 خاص قصير الصلاحية؛ يجب عدم تمرير بيانات اعتماد API إليه · Location |
| 401 | التوثيق المطلوب أو غير صحيح |
| 404 | الموارد التي لم يعثر عليها أو لا يملكها المتصل |
| 409 | النزاع في حالة الموارد أو الافتراض |
| 410 | انتهت صلاحية النتيجة المحتفظ بها |
{
"type": "string"
}ولايات العمل والاحتفاظ بها
لا تزال النتائج متاحة 24 بعد ساعات من كامل Bulk العمل يكتمل. أنقذهم من قبل expiresAt. وسائل الإعلام في وجهة نظرك تتبع سياسة الاحتفاظ ببطنك ويمكن أن تشمل الوظيفة المنجزة أشرطة فيديو فاشلة؛ وقد رفضت سجلات شركة counts.invalid خطوط المدخلات.
| الدولة | الإجراء التالي: |
|---|---|
| awaiting_upload | ارفعي الملف واتصلي بالبدء |
| running | استطلع المعرّف نفسه مع تراجع تدريجي؛ يبيّن input.complete إن كان المسح قد اكتمل. |
| paused | اقرأ pauseReasonاصلحه ثم استأنفه |
| finalizing | انتظروا حزمة النتائج و نشرة واضحة |
| completed | تحميل البيان وكل جزء. تفحص حالة كل صف وخطأه |
| failed / cancelled | تفحص الخطأ و انقذ الولاية ولا ينشر أي بيان ختامي. |
تسليم المخازن
استخدموا الملعب لضبط مزود وفحصوا حقول الطلب بالضبط وتنتمي وثائق تفويض المخزن إلى الجسم المختار للتخزين؛ ولا توثق شركة X-API-Key إلا طلبات شركة FlashData API.
| المصدر | تقديم طلب ميداني | التوصيل |
|---|---|---|
| البيانات الوصفية، المخطوطات، المقابض، التحقق من الترخيص | options.result_storage | اختياري. نسخ NDJSON أجزاء من النتائج ودليل على دلك |
| youtube_download | options.storage | مطلوب. إيصال وسائل الإعلام إلى دلو الخاص بك؛ result_storage و browser_delivery غير مقبولة. |
اعثر على الملفات التي تم تسليمها
يُكتب سجل البيانات أخيرًا ويذكر مفاتيح الكائنات وأحجامها وبصمات SHA-256. وهو يختلف عن سجل FlashData الذي يذكر قيم API href. يستخدم YYYYMMDD في مسارات البيانات تاريخ إنشاء Bulk بتوقيت UTC؛ وفي مسارات الوسائط يستخدم تاريخ رفع كل فيديو بتوقيت UTC. يتطلب تسليم بيانات Bulk إلى OSS نقطة نهاية aliyuncs.com.
وتحتاج قيم أجهزة الإعلام الخاصة file_url إلى مخزنك SDK أو موقعة URL من ذلك المزود. ألف FlashData المفتاح لا يمنح دخول الدلو. وملفات الوجبات الفوقية الاختيارية مخزنة بجانب وسائط الإعلام. وتظهر عمليات التسليم في delivery.retryCount.
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.jsonاستلام موقع الإنجاز على شبكة الإنترنت(ح)
مكان عام HTTPS callback_url خيارات خارجية ولا ترسل شركة Bulk إلا بعد نشر البيان؛ فهي لا ترسل أي أحداث لكل فرد ولا أي حدث لإكمال الأعمال الفاشلة أو الملغاة. حافظ على إستطلاع الوضع كتراجع
- Persist and deduplicate delivery_id, then return 2x promptly. عمليات تسليم تصل إلى ثماني مرات مع التخلف.
- الأحداث غير موقّعة. طابق id وsource مع إيصالك المحفوظ؛ وتحقق من completed عبر Management API الموثَّق قبل وضع الاسترجاع في الطابور. تجاهل الروابط الواردة من حدث لم يُتحقق منه.
{
"source": "youtube_metadata",
"options": {
"include_formats": false,
"include_chapters": false
},
"callback_url": "https://your-app.example/webhooks/flashdata"
}{
"delivery_id": "bulk-completion:bulk_EXAMPLE123",
"id": "bulk_EXAMPLE123",
"source": "youtube_metadata",
"status": "completed",
"links": [
{
"rel": "self",
"href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123",
"method": "GET"
},
{
"rel": "results",
"href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123/results",
"method": "GET"
}
]
}تعاريف الكيماويات
BulkJobCreated
{
"type": "object",
"additionalProperties": false,
"required": [
"job",
"upload"
],
"properties": {
"job": {
"$ref": "#/components/schemas/BulkJob"
},
"upload": {
"type": "object",
"additionalProperties": false,
"required": [
"href",
"method",
"expiresAt",
"contentType"
],
"properties": {
"href": {
"type": "string",
"format": "uri"
},
"method": {
"type": "string",
"const": "PUT"
},
"expiresAt": {
"type": "string",
"format": "date-time"
},
"contentType": {
"type": "string",
"const": "text/plain; charset=utf-8"
}
}
}
}
}BulkJob
{
"type": "object",
"additionalProperties": false,
"required": [
"id",
"source",
"status",
"input",
"counts",
"delivery",
"pauseReason",
"error",
"createdAt",
"startedAt",
"completedAt",
"expiresAt",
"links"
],
"properties": {
"id": {
"type": "string",
"pattern": "^bulk_[A-Za-z0-9_-]{8,}$"
},
"source": {
"type": "string",
"enum": [
"youtube_metadata",
"youtube_transcript",
"youtube_captions",
"youtube_trainability",
"youtube_download"
]
},
"status": {
"type": "string",
"enum": [
"awaiting_upload",
"running",
"paused",
"finalizing",
"completed",
"failed",
"cancelled"
]
},
"input": {
"type": "object",
"additionalProperties": false,
"required": [
"bytes",
"complete",
"scannedBytes",
"scannedLines"
],
"properties": {
"bytes": {
"type": "integer",
"minimum": 0
},
"complete": {
"type": "boolean"
},
"scannedBytes": {
"type": "integer",
"minimum": 0
},
"scannedLines": {
"type": "integer",
"minimum": 0
}
}
},
"counts": {
"type": "object",
"additionalProperties": false,
"required": [
"accepted",
"completed",
"failed",
"invalid",
"results"
],
"properties": {
"accepted": {
"type": "integer",
"minimum": 0
},
"completed": {
"type": "integer",
"minimum": 0
},
"failed": {
"type": "integer",
"minimum": 0
},
"invalid": {
"type": "integer",
"minimum": 0
},
"results": {
"type": "integer",
"minimum": 0
}
}
},
"pauseReason": {
"type": [
"string",
"null"
]
},
"delivery": {
"type": "object",
"additionalProperties": false,
"required": [
"customerStorage",
"storageType",
"uploadedParts",
"retryCount"
],
"properties": {
"customerStorage": {
"type": "boolean"
},
"storageType": {
"type": [
"string",
"null"
],
"enum": [
"s3",
"s3_compatible",
"oss",
"gcs",
"azure",
"cos",
"bos",
"tos",
null
]
},
"uploadedParts": {
"type": "integer",
"minimum": 0
},
"retryCount": {
"type": "integer",
"minimum": 0
}
}
},
"error": {
"oneOf": [
{
"type": "null"
},
{
"type": "object",
"additionalProperties": false,
"required": [
"code",
"detail"
],
"properties": {
"code": {
"type": "string"
},
"detail": {
"type": [
"string",
"null"
]
}
}
}
]
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"startedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completedAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"expiresAt": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"links": {
"type": "array",
"items": {
"$ref": "#/components/schemas/JobLink"
}
}
}
}BulkJobPage
{
"type": "object",
"additionalProperties": false,
"required": [
"data",
"pagination"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BulkJob"
}
},
"pagination": {
"$ref": "#/components/schemas/Pagination"
}
}
}BulkJobResponse
{
"type": "object",
"additionalProperties": false,
"required": [
"job"
],
"properties": {
"job": {
"$ref": "#/components/schemas/BulkJob"
}
}
}CreateBulkJobRequest
{
"type": "object",
"additionalProperties": false,
"required": [
"source"
],
"properties": {
"source": {
"type": "string",
"enum": [
"youtube_metadata",
"youtube_transcript",
"youtube_captions",
"youtube_trainability",
"youtube_download"
]
},
"options": {
"type": "object",
"additionalProperties": true,
"description": "Reused for every ID. Metadata accepts include_formats and include_chapters. Transcript and captions accept language (one code or an array of 1–10 distinct codes) and auto (applies to all requested languages). Omit language to prefer en-orig, fall back to en, and return one track. With auto=true, each requested code tries its -orig track first, then the plain code. Explicit -orig codes and auto=false stay exact. languageCode identifies the selected track; requestedLanguageCode is included when it differs from the requested code. A language array returns tracks and per-language errors for each video with at least one retrieved track. If no track is retrieved, the video job fails and its reserved credits are refunded. Bulk exports use one JSONL record per video. Trainability accepts no source options. These four data sources optionally accept result_storage. Supported storage_type values are s3, s3_compatible, oss, gcs, azure, cos, bos, and tos. storage_url is the bucket name (Azure container name); object_prefix is optional. S3, S3-compatible, OSS, COS, BOS, and TOS use access_key and secret_key. S3-compatible and OSS also require a public HTTPS endpoint_url. COS, BOS, and TOS require region and use fixed provider endpoints. COS bucket names include the APPID. BOS S3-compatible HTTPS delivery supports bj, su, and hkg. GCS requires service_account with project_id, client_email, and private_key. Azure requires account_name and a container SAS sas_token with write permission. Default object_prefix is YYYYMMDD, frozen to the UTC bulk creation date. Files are written to <prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz; manifest.json in the same bulk directory is written last. Each JSONL row includes its input index and completed, failed, or invalid status. Internal R2 results remain available through the result links for 24 hours. Download accepts the normal YouTube download parameters, requires customer storage, and does not permit browser_delivery. Download storage supports the same eight provider types and credential shapes listed above under the storage field. Download storage may include object_prefix; YYYYMMDD tokens resolve to the UTC upload date, while literal prefixes are unchanged."
},
"callback_url": {
"type": "string",
"format": "uri",
"maxLength": 2048,
"description": "Optional public HTTPS endpoint notified once after manifest publication."
}
}
}JobLink
{
"type": "object",
"additionalProperties": false,
"required": [
"rel",
"href",
"method"
],
"properties": {
"rel": {
"type": "string",
"enum": [
"self",
"results",
"content",
"download"
]
},
"href": {
"type": "string",
"format": "uri"
},
"method": {
"type": "string",
"const": "GET"
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"filename": {
"type": "string"
},
"content_type": {
"type": "string"
},
"size_bytes": {
"type": "integer",
"minimum": 1
}
}
}Pagination
{
"type": "object",
"additionalProperties": false,
"required": [
"hasMore",
"limit"
],
"properties": {
"nextCursor": {
"type": [
"string",
"null"
]
},
"previousCursor": {
"type": [
"string",
"null"
]
},
"hasMore": {
"type": "boolean"
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
}
}Problem
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"title",
"status",
"code",
"requestId"
],
"properties": {
"type": {
"type": "string",
"format": "uri-reference"
},
"title": {
"type": "string"
},
"status": {
"type": "integer",
"minimum": 400,
"maximum": 599
},
"code": {
"type": "string",
"pattern": "^[a-z0-9_]+$"
},
"detail": {
"type": "string"
},
"requestId": {
"type": "string",
"pattern": "^req_"
},
"fieldErrors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/FieldError"
}
}
}
}FieldError
{
"type": "object",
"additionalProperties": false,
"required": [
"field",
"code",
"message"
],
"properties": {
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}UpdateBulkJobRequest
{
"type": "object",
"additionalProperties": false,
"minProperties": 1,
"properties": {
"options": {
"type": "object",
"additionalProperties": true,
"description": "Partial option update. Nested storage fields are merged so unchanged credentials do not need to be resent. Data result_storage fields are merged the same way. After all IDs have been scanned, a paused data bulk job accepts credential updates only: access_key and secret_key, GCS service_account, or Azure sas_token, depending on the storage type. The complete merged configuration is validated before it is stored."
},
"callback_url": {
"type": [
"string",
"null"
],
"format": "uri",
"maxLength": 2048,
"description": "Replacement completion callback, or null to remove the callback."
}
}
}