Негізгі мазмұнға өту

Файл жүктеу (File upload)

Бұл нұсқаулық Postmypost API арқылы файлдарды жүктеудің бірнеше қадамнан тұратын процесін сипаттайды. Жалпы алғанда, ол үш қадамнан тұрады:

  1. Жүктеуді инициализациялау — файл метадеректерін жіберіп, параметрлерді алу. Қараңыз: API Файл жүктеуді инициализациялау.
  2. Файлды жүктеу
    • Сценарий A: алдын ала қол қойылған параметрлер арқылы файлды тікелей сақтауға (S3) жүктеу.
    • Сценарий B: сілтеме (URL) бойынша жүктеу, яғни жүйеден файлды өзі алуын сұрайсыз.
  3. Өңдеуді күту және дайындықты тексеру — күйді дайын болғанға дейін сұрау. Қараңыз: API Файл жүктеу күйі.

Алдын ала талаптар​

  • API базалық URL: https://api.postmypost.io/v4.1
  • Аутентификация: барлық Postmypost API сұрауларында Authorization: Bearer <ACCESS_TOKEN> тақырыбын жіберіңіз.
  • Алдын ала project_id (файл жүктелетін жоба ID‑сі) білу қажет.

1‑қадам. Жүктеуді инициализациялау​

POST /upload/init → әдіс құжаттамасы

Сұрау денесінің бір нұсқасын таңдаңыз:

  • "by file": project_id, файл атауы name және байтпен өлшемі size беріңіз.
  • "by URL": project_id және бастапқы файлдың url беріңіз.

Мысал ("by file", cURL):

curl -X POST "https://api.postmypost.io/v4.1/upload/init" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": 12345,
    "name": "cat.jpg",
    "size": 259390
  }'

"by file" нұсқасы үшін сәтті жауап S3‑ке тікелей жүктеуге арналған параметрлерді қайтарады:

{
  "id": 32,
  "name": "cat.jpg",
  "size": 259390,
  "action": "https://uploads.s3.amazonaws.com/",
  "fields": [
    { "key": "acl", "value": "public-read" },
    { "key": "key", "value": "1/79811084-92e0-4cf1-805c-18cc4ec20339" },
    { "key": "X-Amz-Credential", "value": "YCAJEXAMPLE/20250630/ru-central1/s3/aws4_request" },
    { "key": "X-Amz-Algorithm", "value": "AWS4-HMAC-SHA256" },
    { "key": "X-Amz-Date", "value": "20250630T064654Z" },
    { "key": "Policy", "value": "eyJleHBpcmF0aW9uIjoiMjAyNS0wNi0zMF..." },
    { "key": "X-Amz-Signature", "value": "a9e1927a56145161345903c8c081a3194d90f641fed0bc49a651debd2e66a946" }
  ],
  "status": 5
}

id, action және барлық fields[].key → fields[].value жұптарын сақтаңыз — олар кейін қажет болады.

2‑қадам. Файлды жүктеу: сценарийді таңдаңыз​

Сценарий A — сақтауға (S3) тікелей жүктеу​

  1. Файлды action мекенжайына fields параметрлерімен бірге multipart/form-data арқылы жіберіңіз.

Мысал (cURL):

# 1-қадамнан action және fields мәндерін қойыңыз
curl -X POST "https://uploads.s3.amazonaws.com/" \
  -F "acl=public-read" \
  -F "key=1/79811084-92e0-4cf1-805c-18cc4ec20339" \
  -F "X-Amz-Credential=YCAJEXAMPLE/20250630/ru-central1/s3/aws4_request" \
  -F "X-Amz-Algorithm=AWS4-HMAC-SHA256" \
  -F "X-Amz-Date=20250630T064654Z" \
  -F "Policy=eyJleHBpcmF0aW9uIjoiMjAyNS0wNi0zMF..." \
  -F "X-Amz-Signature=a9e1927a56145161345903c8c081a3194d90f641fed0bc49a651debd2e66a946" \
  -F "file=@./cat.jpg"

Сақтаудан күтілетін жауап — 204/201/302. Сәтті жүктегеннен кейін 2‑тармаққа өтіңіз.

  1. Жүктеуді API‑да аяқтаңыз: POST /upload/complete?id=<id> → әдіс құжаттамасы
curl -X POST "https://api.postmypost.io/v4.1/upload/complete?id=32" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Жауап мысалы:

{ "id": 32, "status": 1 }

Сценарий B — URL бойынша жүктеу​

Егер инициализация (1‑қадам) кезінде "by URL" нұсқасын пайдалансаңыз, ештеңені қолмен жүктеудің қажеті жоқ — жүйе файлды өзі жүктеп алады. Бұл сценарийде /upload/complete әдісі шақырылмайды.

Мониторинг үшін бірден 3‑қадамға өтіп, id арқылы күйді сұраңыз.

3‑қадам. Өңдеуді күту және дайындықты тексеру​

GET /upload/status?id=<id> → әдіс құжаттамасы

curl -X GET "https://api.postmypost.io/v4.1/upload/status?id=32" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

Жауап мысалы:

{ "id": 32, "status": 1 }

Мүмкін күйлер:

  • 5 — жүктеуді күту
  • 4 — жүктелуде
  • 3 — өңделуде
  • 2 — қате
  • 1 — файл сәтті жүктелді

Жиі қателер және кеңестер​

  • 401/403: Authorization: Bearer <ACCESS_TOKEN> тақырыбының дұрыстығын және жобаға құқықтарыңызды тексеріңіз.
  • 422: сұрау денесін тексеріңіз — міндетті өрістер:
    • тікелей жүктеу үшін: project_id, name, size
    • URL бойынша жүктеу үшін: project_id, url
  • S3 қадамында fields ішіндегі барлық өрістерді init қайтарғандай дәл беріңіз.
  • multipart/form-data ішінде нақты файл мазмұнын жіберу үшін -F "file=@/path/to/file" пайдаланыңыз.
  • size мәнін байтпен көрсетіңіз.
  • Байланыс үзіліп қалған жағдайда, S3 қадамын қайта орындап, содан кейін /upload/complete әдісін қайта шақыра аласыз (Сценарий A үшін).