آموزش عملی

قبل از نوشتن کد، مدل اتصال را درست بشناسید

پارس‌پک API سازگار با S3 ارائه می‌کند؛ یعنی از AWS SDK زبان خود استفاده می‌کنید، اما Endpoint را برابر آدرس پنل می‌گذارید. این صفحه مفاهیم مشترک همهٔ زبان‌ها را توضیح می‌دهد: معنی هر مقدار، تفاوت Key با مسیر محلی، ترتیب آزمون و الگوی امن لینک موقت.

یک سناریوهفت فرمانخروجی نمونههشت زبان

PHP Laravel Go Python Node.js TypeScript Java C#

نمونه آماده اجرا در هشت زبان

این راهنما چه چیزی را ثابت می‌کند؟

یک فایل کوچک باید آپلود، فهرست، بررسی، دانلود و حذف شود. این چرخه، هم اتصال و هم مجوزهای اصلی Bucket را می‌سنجد.

فرض کنید روی سیستم خودتان فایلی به نام hello.txt دارید. می‌خواهید آن را در باکت خصوصی پارس‌پک با نام tutorial/hello.txt ذخیره کنید. بعد از ذخیره، باید بتوانید در فهرست ببینیدش، حجم و نوعش را بدون دانلود بخوانید، یک کپی روی سرور برنامه بگیرید، اگر لازم شد لینک چند دقیقه‌ای به کاربر بدهید، و در پایان از باکت حذفش کنید.

باکت معمولاً خصوصی است؛ یعنی مرورگر یا اپ موبایل بدون اجازه نمی‌تواند فایل را بخواند یا بنویسد. کلید API را هم نباید به کاربر بدهید، چون با آن کل فضا باز می‌شود. برای همین دو مسیر دارید: یا سرور خودتان فایل را جابه‌جا می‌کند، یا سرور بعد از ورود کاربر یک لینک کوتاه‌عمر می‌سازد.

هر زبان یک برنامه خط فرمان کوچک با همین هفت فرمان دارد. ترتیب اجرا همین است؛ اگر از وسط شروع کنید، فایل هنوز در باکت نیست و head یا download خطا می‌دهد.

ترتیب	فرمان	در این سناریو چه می‌کند
۱	`upload`	فایل محلی `./hello.txt` را با نام `tutorial/hello.txt` در باکت می‌گذارد
۲	`list`	فایل‌هایی را نشان می‌دهد که نامشان با `tutorial/` شروع می‌شود
۳	`head`	حجم، نوع و ETag همان فایل را می‌گوید؛ خود فایل را نمی‌آورد
۴	`download`	فایل را از باکت می‌گیرد و روی دیسک سرور، مثلاً `./downloads/hello.txt`، می‌نویسد
۵	`presign-get`	یک URL موقت می‌سازد تا کاربر همان فایل را مستقیم از فضای ابری بگیرد
۶	`presign-put`	یک URL موقت می‌سازد تا کاربر فایل را مستقیم به باکت بفرستد
۷	`delete`	همان نام را از باکت برمی‌دارد؛ فایل روی سیستم شما دست نمی‌خورد

آپلود خیلی بزرگ، Resume، کپی بین باکت‌ها و تنظیم CORS پنل در این آموزش نیست. اگر از مرورگر بخواهید فایل را با لینک PUT بفرستید، CORS باید جدا در پنل تنظیم شده باشد؛ وگرنه از curl یا سرور خودتان استفاده کنید.

اگر به کد برنامه نیاز ندارید و فقط می‌خواهید از خط فرمان فایل جابه‌جا کنید، آموزش rclone همین Bucket را با یک برنامه خط فرمان آماده پوشش می‌دهد.

پنج مقدار اتصال را از هم تفکیک کنید

Endpoint مقصد شبکه است، Bucket محل نگهداری، Region بخشی از امضا و دو Key هویت برنامه هستند. هر پنج مقدار را از همان سرویس در پنل بردارید.

در پنل پارس‌پک سرویس فضای ابری را باز کنید و مشخصات اتصال را پیدا کنید. معمولاً Endpoint، نام Bucket، Access Key و Secret Key آن‌جا نوشته شده است. Region را خیلی از پنل‌ها نشان نمی‌دهند؛ اگر ندیدید، us-east-1 بگذارید و عوضش نکنید.

Endpoint

آدرس HTTPS همان سرویس شماست، نه آدرس AWS.

شکل معمول شبیه https://c123456.parspack.net است. اسلش انتهایی را بردارید؛ اگر / ته آدرس بماند، امضای درخواست خراب می‌شود و معمولاً SignatureDoesNotMatch می‌گیرید. این آدرس را با Endpoint عمومی AWS عوض نکنید؛ وگرنه درخواست به پارس‌پک نمی‌رسد.

Bucket

نام فضای ذخیره‌سازی شما در همان Endpoint.

اغلب با شناسه داخل Endpoint یکی است؛ مثلاً Endpoint https://c123456.parspack.net و Bucket c123456. اگر این نام با پنل یکی نباشد، خطا NoSuchBucket است. Bucket را در URL به شکل /bucket/key می‌بینید، چون اتصال پارس‌پک باید Path-style باشد.

Region

موقعیت جغرافیایی سرور نیست.

فقط یک رشته برای امضای Signature V4 است. اگر پنل Region نداد، us-east-1 را ثابت نگه دارید. عوض کردنش بدون هماهنگی با سرویس، دوباره همان خطای امضا را می‌آورد.

Access Key و Secret Key

رمز ورود API به باکت شما هستند.

این دو مقدار فقط روی سرور برنامه می‌مانند. اگر به مرورگر یا اپ موبایل برسند، هر کسی که آن‌ها را ببیند می‌تواند فایل‌های باکت را بخواند، بنویسد یا حذف کند. کاربر نهایی حداکثر یک لینک کوتاه‌عمر می‌گیرد، نه این کلیدها.

مقدارهای حساس را بیرون از کد نگه دارید

فایل نمونهٔ .env را کپی و مقدارهای پنل را جایگزین کنید. کدهای نمونه همین نام‌ها را می‌خوانند، پس نام متغیرها را تغییر ندهید.

examples/.env.example

PARSPACK_S3_ENDPOINT=https://c123456.parspack.net
PARSPACK_S3_BUCKET=c123456
PARSPACK_S3_REGION=us-east-1
PARSPACK_S3_ACCESS_KEY=YOUR_ACCESS_KEY
PARSPACK_S3_SECRET_KEY=YOUR_SECRET_KEY

متغیر	چه چیزی در آن می‌گذارید	اگر اشتباه باشد
`PARSPACK_S3_ENDPOINT`	آدرس HTTPS پنل، بدون `/` در انتها	Timeout، اتصال به جای غلط، یا خطای امضا
`PARSPACK_S3_BUCKET`	نام باکت؛ اغلب همان شناسه داخل Endpoint	`NoSuchBucket`
`PARSPACK_S3_REGION`	اگر پنل چیزی نگفت: `us-east-1`	`SignatureDoesNotMatch`
`PARSPACK_S3_ACCESS_KEY`	شناسه دسترسی API از پنل	`AccessDenied` یا خطای امضا
`PARSPACK_S3_SECRET_KEY`	رمز دسترسی API از پنل	`AccessDenied` یا خطای امضا

terminal · ساخت .env برای هر زبان

cp examples/.env.example examples/php/.env
cp examples/laravel/.env.example examples/laravel/.env
cp examples/.env.example examples/go/.env
cp examples/.env.example examples/python/.env
cp examples/.env.example examples/javascript/.env
cp examples/.env.example examples/typescript/.env
cp examples/.env.example examples/java/.env
cp examples/.env.example examples/csharp/.env

فایل .env را Commit نکنید. هر پنج مقدار را از پنل خودتان وارد کنید و اسلش یا فاصلهٔ اضافه در ابتدا و انتهای آن‌ها نگذارید.

Key آدرس فایل در Bucket است

در S3 پوشهٔ واقعی وجود ندارد؛ tutorial/hello.txt یک Key کامل است. مسیر محلی فقط هنگام خواندن داده برای آپلود یا نوشتن خروجی دانلود کاربرد دارد.

در همین آموزش، فایل روی سیستم شما ./hello.txt است. داخل باکت همان محتوا با نام tutorial/hello.txt ذخیره می‌شود. اسلش داخل Key پوشه واقعی روی دیسک نمی‌سازد؛ فقط بخشی از نام است تا بتوانید فایل‌ها را گروه‌بندی کنید. / را ابتدای Key نگذارید.

چیزی که می‌گویید	مثال این آموزش	معنی‌اش چیست
مسیر محلی	`./hello.txt`	فایل روی همین سیستم یا سرور برنامه
Object Key	`tutorial/hello.txt`	نام کامل فایل داخل باکت
Prefix	`tutorial/`	فیلتر فهرست؛ فقط Keyهایی که با این متن شروع می‌شوند
جایگزینی	آپلود دوباره با همان Key	محتوای قبلی همان نام عوض می‌شود؛ نسخه جدا ساخته نمی‌شود
Path-style	`https://c123456.parspack.net/c123456/tutorial/hello.txt`	شکل URL لازم برای پارس‌پک؛ نه `bucket.endpoint`

اجرای list بدون Prefix می‌تواند فهرست بزرگی از کل باکت برگرداند. Prefix را روی tutorial/ می‌گذاریم تا خروجی فقط به فایل‌های آزمایشی محدود بماند.

یک چرخهٔ کامل اجرا کنید

ترتیب عملیات بعدی عمدی است: هر مرحله بخشی از اتصال و مجوزها را می‌سنجد. صفحهٔ هر زبان، فرمان اجرا و کد کامل همان مرحله را دارد.

اول یک فایل محلی بسازید، بعد از ریشه این مستندات فرمان‌ها را پشت سر هم بزنید. اگر .env هنوز مقدار پنل ندارد، همه فرمان‌ها همان اول شکست می‌خورند.

terminal · ساخت فایل نمونه

printf 'hello ParsPack\n' > hello.txt

آپلود: فایل را در باکت بگذارید

upload ./hello.txt tutorial/hello.txt

برنامه فایل محلی را می‌خواند و با نام Key در باکت ذخیره می‌کند. ETag اثر انگشت محتواست؛ اگر بعداً همان فایل را دوباره آپلود کنید و محتوا یکی باشد، ETag هم یکی می‌ماند. اگر محتوا فرق کند، فایل قبلی با همان نام عوض می‌شود.

خروجی نمونه

{ "ok": true, "operation": "upload", "key": "tutorial/hello.txt", "etag": "..." }

فهرست: ببینید فایل ذخیره شده

list tutorial/

این فرمان خود فایل را نمی‌آورد؛ فقط نام، حجم و زمان تغییر را برای Keyهایی برمی‌گرداند که با Prefix شروع می‌شوند. اگر آرایه objects خالی بود، یا آپلود انجام نشده یا Prefix را اشتباه نوشته‌اید — مثلاً tutorial بدون اسلش ممکن است چیز دیگری را هم نشان بدهد، ولی Tutorial/ با حرف بزرگ هیچ‌کدام از فایل‌های این سناریو را پیدا نمی‌کند.

خروجی نمونه

{ "ok": true, "prefix": "tutorial/", "objects": [ { "key": "tutorial/hello.txt", "bytes": 14, "last_modified": "2026-08-18T10:00:00+00:00" } ] }

مشخصات: حجم و نوع را بدون دانلود بخوانید

head tutorial/hello.txt

وقتی فقط می‌خواهید بدانید فایل هست یا نه، یا حجمش چقدر است، head کافی است. اگر آن Key در باکت نباشد، معمولاً 404 می‌گیرید نه پیام دوستانه «فایل پیدا نشد». این را با download عوض نکنید؛ Head بدنه فایل را منتقل نمی‌کند.

خروجی نمونه

{ "ok": true, "key": "tutorial/hello.txt", "bytes": 14, "content_type": "text/plain", "etag": "...", "last_modified": "2026-08-18T10:00:00+00:00" }

دانلود روی سرور: فایل را روی دیسک برنامه بنویسید

download tutorial/hello.txt ./downloads/hello.txt

این فرمان فایل را از باکت می‌گیرد و روی همین سیستم ذخیره می‌کند. کاربر سایت آن را نمی‌بیند مگر خودتان بعداً برایش بفرستید. وقتی به آن نیاز دارید که سرور باید فایل را پردازش کند، در ایمیل ضمیمه کند، یا در جای دیگری نگه دارد. پوشه downloads اگر نباشد، نمونه آن را می‌سازد.

خروجی نمونه

{ "ok": true, "operation": "download", "key": "tutorial/hello.txt", "local_file": "./downloads/hello.txt", "bytes": 14 }

لینک موقت دانلود: فایل را به کاربر بدهید بدون اینکه کلید بدهید

presign-get tutorial/hello.txt 900

900 یعنی پانزده دقیقه. خروجی یک URL است، نه خود فایل. اگر این آدرس را در مرورگر باز کنید یا به curl --output بدهید، فضای ابری همان یک فایل را برمی‌گرداند. بعد از انقضا آدرس کار نمی‌کند. این فرمان را با download قاطی نکنید: یکی فایل را روی سرور شما می‌نویسد، دیگری فقط آدرس موقت می‌سازد.

خروجی نمونه

{ "ok": true, "operation": "presign-get", "key": "tutorial/hello.txt", "method": "GET", "expires_in": 900, "url": "https://c123456.parspack.net/c123456/tutorial/hello.txt?X-Amz-..." }

لینک موقت آپلود: کاربر فایل را مستقیم به باکت بفرستد

presign-put tutorial/upload.txt text/plain 900

اینجا فایل از سرور شما رد نمی‌شود. سرور فقط نام (tutorial/upload.txt) و نوع (text/plain) را قفل می‌کند و URL می‌سازد. کسی که URL را دارد، فقط می‌تواند همان نام را با همان نوع، با روش PUT، تا پایان انقضا بنویسد. اگر موقع ارسال Content-Type فرق کند، معمولاً خطای امضا می‌گیرید.

خروجی نمونه

{ "ok": true, "operation": "presign-put", "key": "tutorial/upload.txt", "method": "PUT", "headers": { "Content-Type": "text/plain" }, "expires_in": 900, "url": "https://c123456.parspack.net/c123456/tutorial/upload.txt?X-Amz-..." }

حذف: نام را از باکت بردارید

delete tutorial/hello.txt

فایل داخل باکت حذف می‌شود. کپی محلی روی سیستم شما می‌ماند. اگر آن نام از قبل در باکت نباشد، خیلی از سرویس‌ها باز هم پاسخ موفق می‌دهند؛ بنابراین برنامه خودتان باید بداند کدام Key را حذف کرده است، نه اینکه به «موفق بودن پاسخ» اعتماد کند.

خروجی نمونه

{ "ok": true, "operation": "delete", "key": "tutorial/hello.txt" }

لینک امضاشده را یک مجوز موقت بدانید

سرور پس از احراز هویت، URL را برای یک Key، یک متد و زمان محدود می‌سازد. مرورگر فقط همین URL را می‌گیرد؛ Secret Key هرگز از سرور خارج نمی‌شود.

باکت خصوصی است. اگر کلید API را در فرانت‌اند بگذارید، هر کسی می‌تواند کل فضا را بخواند. اگر همه فایل‌ها را از سرور خودتان عبور دهید، پهنای باند و حافظه سرور بی‌خودی پر می‌شود. لینک امضاشده وسط این دو است: سرور هویت را چک می‌کند، بعد فقط یک کار مشخص روی یک فایل را برای چند دقیقه باز می‌کند. از آن به بعد مرورگر مستقیم با فضای ابری حرف می‌زند.

۱. درخواستکاربر در برنامه شما روی دانلود یا آپلود می‌زند

۲. مجوزسرور ورود و دسترسی همان فایل را چک می‌کند

۳. ساخت لینکSDK با کلید سرور یک URL زمان‌دار می‌سازد

۴. مصرفمرورگر همان URL را مستقیم به فضای ابری می‌فرستد

GET

دانلود فاکتور بعد از ورود

مثال روزمره برای Presigned GET

کاربر وارد حساب می‌شود و روی «دانلود فاکتور» می‌زند. سرور بررسی می‌کند این فاکتور مال همین کاربر است، Key را خودش می‌سازد — مثلاً invoices/42.pdf — و یک URL پانزده دقیقه‌ای برمی‌گرداند. فرانت‌اند همان آدرس را در <a href> می‌گذارد یا پنجره دانلود باز می‌کند. فایل از سرور شما رد نمی‌شود.

مصرف لینک Header اضافه نمی‌خواهد. همان URL را باز کنید، یا با curl فایل را بگیرید:

curl · مصرف لینک موقت دانلود

curl --output invoice.pdf "$SIGNED_DOWNLOAD_URL"

PUT

آپلود عکس از مرورگر

مثال روزمره برای Presigned PUT

کاربر عکس پروفایل را انتخاب می‌کند. سرور Key را خودش تعیین می‌کند — مثلاً users/123/avatar.jpg — و نوع را image/jpeg قفل می‌کند، بعد URL می‌سازد. مرورگر بدنه فایل را با PUT به همان آدرس می‌فرستد. کاربر نمی‌تواند فایل دیگری را عوض کند، چون نام در امضا قفل شده است.

موقع ارسال، Content-Type باید دقیقاً همان مقدار زمان ساخت لینک باشد. از مرورگر این کار فقط وقتی درست است که CORS باکت، دامنه سایت شما را مجاز کرده باشد؛ وگرنه از curl یا سرور خودتان استفاده کنید.

curl · مصرف لینک موقت آپلود

curl --request PUT \
--header 'Content-Type: text/plain' \
--upload-file ./hello.txt \
"$SIGNED_UPLOAD_URL"

	Presigned GET	Presigned PUT
Method	`GET`	`PUT`
ورودی امضا	Bucket، Key، انقضا	Bucket، Key، Content-Type، انقضا
کاربر چه کار می‌کند	همان URL را باز می‌کند یا با GET فایل را می‌گیرد	بدنه فایل را با همان نوع به همان URL می‌فرستد
جایگزین کدام فرمان سرور است	جایگزین `download` برای کاربر نهایی	جایگزین `upload` وقتی فایل نباید از سرور شما عبور کند

قبل از ساخت لینک، هویت کاربر و حق دسترسی همان فایل را در سرور چک کنید. Key را خود سرور بسازد، نه ورودی خام کاربر. لینک را کوتاه نگه دارید؛ نمونه این مستندات پیش‌فرض ۱۵ دقیقه است و حداکثر ۷ روز (۶۰۴۸۰۰ ثانیه) را می‌پذیرد.

خطا را از لایهٔ درست پیدا کنید

خطای DNS با اشتباه Credential یا نبودن Key یکی نیست. کد HTTP و نام خطا را از stderr بردارید و بعد ردیف مرتبط جدول را بررسی کنید.

اگر upload شکست خورد، ابتدا Endpoint بدون اسلش انتها، نام Bucket، Region و دو کلید را با پنل مقایسه کنید. پس از برقراری اتصال، املای Key و مجوز همان عملیات را بررسی کنید.

خطا	علت معمول	بررسی
`SignatureDoesNotMatch`	امضای درخواست با تنظیمات یکی نیست	Slash انتهای Endpoint، Region ثابت، کلیدها، و `Content-Type` در PUT
`AccessDenied`	کلید یا دسترسی Bucket کافی نیست	مقدارهای پنل و نوع دسترسی کاربر فضای ابری
`NoSuchBucket`	نام Bucket با پنل یکی نیست	`PARSPACK_S3_BUCKET`
`404` در Head یا Download	این Key در Bucket نیست	املای Key؛ اول `list` همان Prefix را بزنید
Timeout / connection	Endpoint در دسترس نیست	آدرس HTTPS پنل، بدون تغییر و بدون `/` انتها
Local file not found	مسیر فایل روی سیستم اشتباه است	مسیر را نسبت به جایی که فرمان را اجرا کرده‌اید چک کنید

حالا صفحه زبان خود را باز کنید

نصب SDK، ساخت Client و کد هر فرمان آن‌جاست. مقدارهای پنل و ترتیب فرمان‌ها را از همین صفحه ببرید.

صفحهٔ هر زبان یک برنامهٔ اجرایی برای آزمون hello.txt دارد. وقتی آپلود، فهرست و دانلود بدون خطا انجام شد، Key و مسیر محلی را با مقدارهای واقعی برنامهٔ خودتان جایگزین کنید.

project tree

examples/
├── .env.example
├── php/
│   ├── composer.json
│   └── parspack_s3.php
├── laravel/
│   ├── composer.json
│   ├── config/filesystems.php
│   └── app/Console/Commands/ParspackS3.php
├── go/
│   ├── go.mod
│   └── main.go
├── python/
│   ├── requirements.txt
│   └── parspack_s3.py
├── javascript/
│   ├── package.json
│   └── parspack_s3.js
├── typescript/
│   ├── package.json
│   ├── tsconfig.json
│   └── parspack_s3.ts
├── java/
│   ├── pom.xml
│   └── src/main/java/.../ParspackS3.java
└── csharp/
  ├── ParspackS3.csproj
  └── Program.cs

صفحه زبان خود را باز کنید.نصب، اتصال و هفت فرمان با کد همان زبان آن‌جاست.

PHP Laravel Go Python Node.js TypeScript Java C#