PP مستندات فضای ابری پارس‌پک
Java 17+ · Maven · AWS SDK for Java 2.x

S3Client و S3Presigner را جدا بسازید

در AWS SDK for Java v2، عملیات S3 و امضای URL دو مسئولیت جدا هستند. این نمونه هر دو Client را با Region، Credential، Endpoint و path-style یکسان می‌سازد و با try-with-resources چرخهٔ عمر آن‌ها را مدیریت می‌کند.

AWS SDK v2MavenPresigned GET و PUT
برنامه Java متصل به فضای ذخیره‌سازی
هفت فرمان با خروجی JSON

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

نمونه خروجی استاندارد را JSON نگه می‌دارد تا در اسکریپت و CI هم قابل مصرف باشد.

۱

پیش‌نیاز و نصب SDK

اول کتابخانه همین پوشه را نصب کنید. بدون این قدم، نمونه اجرا نمی‌شود.

فرمان را از ریشه همین مستندات بزنید. اگر نصب درست باشد، وابستگی‌ها داخل پوشه زبان می‌مانند و لازم نیست آن‌ها را جهانی نصب کنید.
terminal · نصب و بررسی
(cd examples/java && mvn -q compile)
ساختار فایل‌ها
examples/java/
├── .env                # پس از کپی‌کردن فایل نمونه ساخته می‌شود
├── pom.xml             # وابستگی‌های Maven
└── src/main/java/com/parspack/examples/ParspackS3.java
۲

ساخت فایل .env

پنج مقدار را از پنل فضای ابری پارس‌پک کپی کنید. معنی هر متغیر و شکل معمول Endpoint در صفحه شروع آمده است.

بعد از کپی، فقط مقدارها را عوض کنید؛ نام متغیرها را کوتاه نکنید. اگر اسلش ته Endpoint بماند یا Region را بی‌دلیل عوض کنید، اولین upload با خطای امضا می‌خوابد.
terminal
cp examples/.env.example examples/java/.env
examples/java/.env
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 پنل، بدون / در انتها؛ شکل معمول https://c123456.parspack.netTimeout یا خطای امضا
PARSPACK_S3_BUCKETنام باکت؛ اغلب با شناسه داخل Endpoint یکی استNoSuchBucket
PARSPACK_S3_REGIONفقط برای امضای Signature V4 است. اگر پنل Region نداد، us-east-1 را ثابت نگه داریدSignatureDoesNotMatch
PARSPACK_S3_ACCESS_KEY / SECRET_KEYکلیدهای API از پنل؛ فقط روی سرورAccessDenied یا خطای امضا
!

فایل .env را Commit نکنید. Access Key و Secret Key فقط روی سرور می‌مانند؛ مرورگر فقط لینک کوتاه‌عمر می‌گیرد.

۳

اتصال برنامه به فضای پارس‌پک

Client را یک بار با مقدارهای .env بسازید. همین شیء برای هر هفت فرمان کافی است.

این تنظیمات SDK را به باکت شما وصل می‌کند، نه به AWS. Endpoint همان آدرس HTTPS پنل است؛ اسلش انتها را بردارید. Region موقعیت سرور نیست؛ اگر پنل چیزی نگفت us-east-1 را عوض نکنید. Path-style باید روشن باشد تا URL به شکل /bucket/key ساخته شود، نه bucket.endpoint.
Access Key و Secret Key فقط روی سرور می‌مانند. مرورگر حداکثر لینک کوتاه‌عمر می‌گیرد. Client را یک بار هنگام شروع برنامه بسازید و بین درخواست‌ها دوباره نسازید.
Java · اتصال
String endpoint = required(env, "PARSPACK_S3_ENDPOINT").replaceAll("/+$", "");

S3Configuration serviceConfig = S3Configuration.builder()
  .pathStyleAccessEnabled(true)
  .build();

S3Client s3 = S3Client.builder()
  .endpointOverride(URI.create(endpoint))
  .region(Region.of(region))
  .credentialsProvider(credentials)
  .serviceConfiguration(serviceConfig)
  .httpClientBuilder(UrlConnectionHttpClient.builder())
  .build();

S3Presigner presigner = S3Presigner.builder()
  .endpointOverride(URI.create(endpoint))
  .region(Region.of(region))
  .credentialsProvider(credentials)
  .serviceConfiguration(serviceConfig)
  .build();
۴

آپلود فایل با putObject

اولین فرمان سناریو: فایل محلی را با یک نام مشخص در باکت بگذارید.

فایل روی سیستم شما ./hello.txt است؛ داخل باکت با نام tutorial/hello.txt ذخیره می‌شود. اسلش پوشه واقعی نمی‌سازد، فقط بخشی از نام است. ETag اثر انگشت محتواست. اگر همین نام از قبل در باکت باشد، محتوای قبلی عوض می‌شود.
Java · آپلود فایل به باکت
Path localFile = Path.of("./hello.txt");
String contentType = Files.probeContentType(localFile);
if (contentType == null) {
  contentType = "application/octet-stream";
}

PutObjectResponse response = s3.putObject(
  PutObjectRequest.builder()
      .bucket(bucket)
      .key("tutorial/hello.txt")
      .contentType(contentType)
      .build(),
  RequestBody.fromFile(localFile)
);

System.out.println(response.eTag());
پارامترمثالکاربرد
Bucketاز .envمحل ذخیره Object
Keytutorial/hello.txtنام کامل Object در S3
RequestBodyRequestBody.fromFileبایت‌های فایل محلی
ContentTypetext/plainنوع محتوای فایل
terminal
(cd examples/java && mvn -q exec:java -Dexec.args="upload ../../hello.txt tutorial/hello.txt")
خروجی نمونه
{ "ok": true, "operation": "upload", "key": "tutorial/hello.txt", "etag": "..." }
!

اگر tutorial/hello.txt از قبل وجود داشته باشد، Upload جدید همان Key را جایگزین می‌کند.

۵

فهرست فایل‌ها و مشخصات یک فایل

بعد از آپلود، اول ببینید فایل در فهرست هست؛ بعد حجم و نوع را بدون دانلود بخوانید.

list tutorial/ خود فایل را نمی‌آورد؛ فقط نام، حجم و زمان تغییر فایل‌هایی را برمی‌گرداند که با این Prefix شروع می‌شوند. اگر آرایه خالی بود، یا آپلود انجام نشده یا Prefix را اشتباه نوشته‌اید.
head وقتی لازم است که فقط بخواهید بدانید فایل هست یا نه، یا حجم و نوعش چیست. اگر Key نباشد معمولاً 404 می‌گیرید. این فرمان را با دانلود عوض نکنید؛ بدنه فایل را منتقل نمی‌کند.
Java · فهرست فایل‌ها
ListObjectsV2Iterable pages = s3.listObjectsV2Paginator(
  ListObjectsV2Request.builder()
      .bucket(bucket)
      .prefix("tutorial/")
      .build()
);

for (ListObjectsV2Response page : pages) {
  page.contents().forEach(object ->
      System.out.println(object.key() + " — " + object.size())
  );
}
terminal
(cd examples/java && mvn -q exec:java -Dexec.args="list tutorial/")
خروجی نمونه
{ "ok": true, "prefix": "tutorial/", "objects": [ { "key": "tutorial/hello.txt", "bytes": 14, "last_modified": "2026-08-18T10:00:00+00:00" } ] }
Java · مشخصات یک فایل
HeadObjectResponse info = s3.headObject(
  HeadObjectRequest.builder()
      .bucket(bucket)
      .key("tutorial/hello.txt")
      .build()
);

System.out.println(info.contentLength());
System.out.println(info.contentType());
terminal
(cd examples/java && mvn -q exec:java -Dexec.args="head tutorial/hello.txt")
خروجی نمونه
{ "ok": true, "key": "tutorial/hello.txt", "bytes": 14, "content_type": "text/plain", "etag": "...", "last_modified": "2026-08-18T10:00:00+00:00" }
Prefixاگر tutorial/ بگذارید، فقط فایل‌هایی که نامشان با این مقدار شروع می‌شود دیده می‌شوند.
Paginatorکلاس ListObjectsV2Iterable همه صفحه‌های نتیجه را پشت سر هم می‌خواند.
Headحجم، نوع، ETag و زمان تغییر را می‌گوید؛ خود فایل را دانلود نمی‌کند.
Key ناموجودHeadObject برای Key ناموجود معمولاً خطای 404 می‌دهد.
۶

دانلود روی سرور

فایل را از باکت بگیرید و روی دیسک همین برنامه بنویسید. این کار لینک برای کاربر نمی‌سازد.

این فرمان فایل را از باکت می‌گیرد و روی دیسک همین برنامه می‌نویسد. کاربر سایت آن را نمی‌بیند مگر خودتان بعداً برایش بفرستید. وقتی به آن نیاز دارید که سرور باید فایل را پردازش کند، در ایمیل ضمیمه کند، یا جای دیگری نگه دارد. پوشه مقصد اگر نباشد، نمونه آن را می‌سازد.
Java · ذخیره فایل روی سرور
s3.getObject(
  GetObjectRequest.builder()
      .bucket(bucket)
      .key("tutorial/hello.txt")
      .build(),
  ResponseTransformer.toFile(Path.of("./downloads/hello.txt"))
);
terminal
(cd examples/java && mvn -q exec:java -Dexec.args="download tutorial/hello.txt ../../downloads/hello.txt")
خروجی نمونه
{ "ok": true, "operation": "download", "key": "tutorial/hello.txt", "local_file": "./downloads/hello.txt", "bytes": 14 }
۷

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

این فرمان را با دانلود روی سرور قاطی نکنید. اینجا فایل روی دیسک شما نوشته نمی‌شود؛ فقط یک آدرس زمان‌دار ساخته می‌شود. جریان کامل در صفحه شروع است.

باکت خصوصی است و کلید API را نباید به کاربر بدهید. این کد فایل را ذخیره نمی‌کند؛ فقط یک URL چند دقیقه‌ای می‌سازد. مثال: کاربر بعد از ورود روی «دانلود فاکتور» می‌زند، سرور مجوز را چک می‌کند، لینک را برمی‌گرداند، مرورگر همان آدرس را باز می‌کند. فایل از سرور شما رد نمی‌شود.
همان URL را در مرورگر باز کنید، در <a href> بگذارید، یا با curl --output file.pdf "$URL" بگیرید. Header اضافه لازم نیست. 900 یعنی پانزده دقیقه؛ بعد از آن آدرس کار نمی‌کند.
Java · ساخت لینک موقت دانلود
PresignedGetObjectRequest download = presigner.presignGetObject(
  GetObjectPresignRequest.builder()
      .signatureDuration(Duration.ofMinutes(15))
      .getObjectRequest(r -> r.bucket(bucket).key(objectKey))
      .build()
);

String downloadUrl = download.url().toString();
terminal
(cd examples/java && mvn -q exec:java -Dexec.args="presign-get tutorial/hello.txt 900")
خروجی نمونه
{ "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-..." }
curl · گرفتن فایل با لینک موقت دانلود
curl --output invoice.pdf "$SIGNED_DOWNLOAD_URL"
!

لینک را کوتاه نگه دارید؛ بین ۱ ثانیه تا ۷ روز (۶۰۴۸۰۰ ثانیه). فقط همان Key را می‌خواند. لینک را فقط بعد از ورود کاربر و چک مجوز بسازید.

۸

لینک موقت آپلود مستقیم

کاربر فایل را از مرورگر به باکت می‌فرستد. فایل از سرور شما رد نمی‌شود و کلید API هم به کاربر نمی‌رسد.

وقتی کاربر باید فایل را از مرورگر بفرستد، ولی نباید کلید را ببیند و نباید کل فایل از سرور شما عبور کند، سرور نام و نوع را خودش قفل می‌کند و URL می‌سازد. مثال: آپلود عکس پروفایل. کاربر فقط حق دارد همان یک نام را با روش PUT بنویسد.
بدنه فایل را با PUT به همان URL بفرستید و Content-Type را دقیقاً همان مقدار زمان ساخت لینک بگذارید؛ وگرنه معمولاً خطای امضا می‌گیرید. از مرورگر فقط وقتی کار می‌کند که CORS باکت سایت شما را مجاز کرده باشد؛ وگرنه از curl یا سرور خودتان استفاده کنید.
Java · ساخت لینک موقت آپلود
String contentType = "text/plain";

PresignedPutObjectRequest upload = presigner.presignPutObject(
  PutObjectPresignRequest.builder()
      .signatureDuration(Duration.ofMinutes(15))
      .putObjectRequest(r -> r.bucket(bucket).key(objectKey).contentType(contentType))
      .build()
);

String uploadUrl = upload.url().toString();
terminal
(cd examples/java && mvn -q exec:java -Dexec.args="presign-put tutorial/upload.txt text/plain 900")
خروجی نمونه
{ "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-..." }
curl · فرستادن فایل با لینک موقت آپلود
curl --request PUT \
--header 'Content-Type: text/plain' \
--upload-file ./hello.txt \
"$SIGNED_UPLOAD_URL"
مرورگر · fetch آپلود
await fetch(signed.url, {
method: "PUT",
headers: { "Content-Type": signed.headers["Content-Type"] },
body: file,
});
Presigned GETPresigned PUT
MethodGETPUT
ورودی امضاBucket، Key، انقضاBucket، Key، Content-Type، انقضا
جایگزین کدام فرمان سرور استجایگزین download برای کاربر نهاییجایگزین upload وقتی فایل نباید از سرور شما عبور کند
!

اگر موقع ساخت لینک text/plain گذاشته‌اید، هنگام ارسال هم باید همان را بفرستید. از مرورگر این کار فقط وقتی درست است که CORS باکت سایت شما را مجاز کرده باشد؛ وگرنه از curl یا سرور خودتان استفاده کنید.

۹

حذف فایل با deleteObject

نام را از باکت برمی‌دارد. لازم نیست اول دانلودش کنید. فایل روی سیستم شما دست نمی‌خورد.

اگر آن نام در باکت نباشد، معمولاً باز هم پاسخ موفق می‌آید. پس خود برنامه باید بداند کدام Key را حذف کرده است، نه اینکه فقط به موفق بودن پاسخ اعتماد کند.
Java · حذف از باکت
s3.deleteObject(
  DeleteObjectRequest.builder()
      .bucket(bucket)
      .key("tutorial/hello.txt")
      .build()
);
terminal
(cd examples/java && mvn -q exec:java -Dexec.args="delete tutorial/hello.txt")
خروجی نمونه
{ "ok": true, "operation": "delete", "key": "tutorial/hello.txt" }
۱۰

اطلاعات S3Exception را دور نریزید

نام و پیام exception روی stderr چاپ می‌شود و برنامه با کد غیرصفر تمام می‌شود. برای عیب‌یابی دقیق‌تر، Status Code و جزئیات پاسخ سرویس را نیز در لاگ کنترل‌شده نگه دارید.

Java · catch
} catch (Exception error) {
  System.err.println(error.getClass().getSimpleName() + ": " + error.getMessage());
  System.exit(1);
}
خطاعلت معمولبررسی
Local file not foundمسیر فایل محلی اشتباه استمسیر را نسبت به پوشه examples/java بررسی کنید
AccessDeniedکلید یا دسترسی Bucket کافی نیستمقدارهای پنل و نوع دسترسی کاربر فضای ابری
SignatureDoesNotMatchامضای درخواست با تنظیمات یکی نیستSlash انتهای Endpoint، Region، کلیدها و Content-Type در PUT
NoSuchBucketنام Bucket با مقدار پنل یکی نیستPARSPACK_S3_BUCKET
Timeout / connectionEndpoint در دسترس نیست یا HTTPS قطع استآدرس پنل را بدون تغییر و بدون / انتها وارد کنید
۱۱

اجرای کامل همین سناریو

فایل همراه مستندات، Loader فایل .env، اعتبارسنجی ورودی، تشخیص Content-Type و خروجی JSON را یک‌جا دارد و S3Client و S3Presigner را با try-with-resources می‌بندد. اگر خروجی هر فرمان شبیه نمونه‌های بالا بود، می‌توانید Key و مسیر را با نام فایل‌های برنامه خودتان عوض کنید.

terminal · از ابتدا تا انتها
(cd examples/java && mvn -q compile)
cp examples/.env.example examples/java/.env

# مقدارهای .env را کامل کنید
printf 'hello ParsPack\n' > hello.txt
(cd examples/java && mvn -q exec:java -Dexec.args="upload ../../hello.txt tutorial/hello.txt")
(cd examples/java && mvn -q exec:java -Dexec.args="list tutorial/")
(cd examples/java && mvn -q exec:java -Dexec.args="head tutorial/hello.txt")
(cd examples/java && mvn -q exec:java -Dexec.args="download tutorial/hello.txt ../../downloads/hello.txt")
(cd examples/java && mvn -q exec:java -Dexec.args="presign-get tutorial/hello.txt 900")
(cd examples/java && mvn -q exec:java -Dexec.args="presign-put tutorial/upload.txt text/plain 900")
(cd examples/java && mvn -q exec:java -Dexec.args="delete tutorial/hello.txt")
Spring BootS3Client و S3Presigner را به‌صورت Bean بسازید و در Storage service تزریق کنید.
Key کنترل‌شدهKey را در Backend بسازید و نتیجه Upload را کنار رکورد مربوط در Database نگه دارید.
Resourceهر دو Client را با try-with-resources ببندید یا در Application shutdown مدیریت کنید.
خطای APIS3Exception را به Status مناسب برنامه خود تبدیل کنید.
پروژهٔ Java آماده است.کد کامل به‌همراه pom.xml در این zip است؛ کافی است باز کنید و با Maven اجرا کنید.
دریافت java.zip