সংযুক্তি আপলোড করুন

জিমেইল এপিআই আপনাকে ড্রাফট তৈরি বা আপডেট করার সময় অথবা মেসেজ পাঠানো বা যোগ করার সময় ফাইল ডেটা আপলোড করার সুযোগ দেয়।

আপলোড বিকল্পগুলি

জিমেইল এপিআই আপনাকে নির্দিষ্ট ধরণের বাইনারি ডেটা বা মিডিয়া আপলোড করার সুযোগ দেয়। আপনি যে ডেটা আপলোড করতে পারবেন তার সুনির্দিষ্ট বৈশিষ্ট্যগুলো মিডিয়া আপলোড সমর্থনকারী যেকোনো পদ্ধতির রেফারেন্স পৃষ্ঠায় উল্লেখ করা আছে:

• সর্বোচ্চ আপলোড ফাইলের আকার : এই পদ্ধতিতে আপনি সর্বোচ্চ যে পরিমাণ ডেটা সংরক্ষণ করতে পারবেন।
• অনুমোদিত মিডিয়া MIME টাইপসমূহ : যে ধরনের বাইনারি ডেটা আপনি এই পদ্ধতি ব্যবহার করে সংরক্ষণ করতে পারেন।

আপনি নিম্নলিখিত যেকোনো উপায়ে আপলোড অনুরোধ করতে পারেন। uploadType রিকোয়েস্ট প্যারামিটারের মাধ্যমে আপনি যে পদ্ধতিটি ব্যবহার করছেন তা নির্দিষ্ট করুন।

• সাধারণ আপলোড : uploadType=media । ছোট ফাইল, যেমন ৫ মেগাবাইট বা তার কম, দ্রুত স্থানান্তরের জন্য।
• মাল্টিপার্ট আপলোড : uploadType=multipart । ছোট ফাইল এবং মেটাডেটা দ্রুত স্থানান্তরের জন্য; এটি ফাইলটিকে তার বর্ণনাকারী মেটাডেটাসহ একটিমাত্র অনুরোধেই স্থানান্তর করে।
• পুনরায় শুরুযোগ্য আপলোড : uploadType=resumable । নির্ভরযোগ্য স্থানান্তরের জন্য, যা বিশেষ করে বড় ফাইলের ক্ষেত্রে গুরুত্বপূর্ণ। এই পদ্ধতিতে, আপনি একটি সেশন শুরু করার অনুরোধ ব্যবহার করেন, যাতে ঐচ্ছিকভাবে মেটাডেটা অন্তর্ভুক্ত থাকতে পারে। বেশিরভাগ অ্যাপ্লিকেশনের জন্য এটি একটি ভালো কৌশল, কারণ এটি প্রতি আপলোডে একটি অতিরিক্ত HTTP অনুরোধের বিনিময়ে ছোট ফাইলের জন্যও কাজ করে।

মিডিয়া আপলোড করার সময় একটি বিশেষ URI ব্যবহার করা হয়। প্রকৃতপক্ষে, যে পদ্ধতিগুলো মিডিয়া আপলোড সমর্থন করে, সেগুলোর দুটি URI এন্ডপয়েন্ট থাকে:

• মিডিয়ার জন্য /upload URI। আপলোড এন্ডপয়েন্টের ফরম্যাটটি হলো স্ট্যান্ডার্ড রিসোর্স URI, যার শুরুতে “/upload” প্রিফিক্স থাকে। সরাসরি মিডিয়া ডেটা স্থানান্তর করার সময় এই URI-টি ব্যবহার করুন।

  উদাহরণ: POST /upload/gmail/v1/users/ userId /messages/send

• মেটাডেটার জন্য এটি হলো স্ট্যান্ডার্ড রিসোর্স ইউআরআই। রিসোর্সটিতে যদি কোনো ডেটা ফিল্ড থাকে, তবে আপলোড করা ফাইলের বর্ণনাকারী মেটাডেটা সংরক্ষণের জন্য সেই ফিল্ডগুলো ব্যবহৃত হয়। মেটাডেটার মান তৈরি বা আপডেট করার সময় আপনি এই ইউআরআই ব্যবহার করতে পারেন।

  উদাহরণ: POST /gmail/v1/users/ userId /messages/send

সহজ আপলোড

ফাইল আপলোড করার সবচেয়ে সহজ পদ্ধতি হলো একটি সাধারণ আপলোড অনুরোধ করা। এই বিকল্পটি একটি ভালো পছন্দ যখন:

• ফাইলটি এতটাই ছোট যে সংযোগ বিচ্ছিন্ন হয়ে গেলেও এটিকে সম্পূর্ণভাবে আবার আপলোড করা যাবে।
• পাঠানোর জন্য কোনো মেটাডেটা নেই। যদি আপনি এই রিসোর্সের জন্য মেটাডেটা একটি আলাদা অনুরোধে পাঠানোর পরিকল্পনা করেন, অথবা যদি কোনো মেটাডেটা সমর্থিত বা উপলব্ধ না থাকে, তাহলে এটি সত্যি হতে পারে।

সাধারণ আপলোড ব্যবহার করতে, মেথডটির /upload URI-তে একটি POST বা PUT রিকোয়েস্ট পাঠান এবং uploadType=media কোয়েরি প্যারামিটারটি যোগ করুন। উদাহরণস্বরূপ:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=media

একটি সাধারণ আপলোড অনুরোধ করার সময় যে HTTP হেডারগুলি ব্যবহার করতে হয়, সেগুলি হলো:

• Content-Type . এপিআই রেফারেন্সে উল্লেখিত, মেথডটির স্বীকৃত আপলোড মিডিয়া ডেটা টাইপগুলোর মধ্যে একটিতে সেট করুন।
• Content-Length . আপনি যে পরিমাণ বাইট আপলোড করছেন, সেই সংখ্যায় সেট করুন। যদি আপনি chunked transfer encoding ব্যবহার করেন, তবে এর প্রয়োজন নেই।

উদাহরণ: সাধারণ আপলোড

নিম্নলিখিত উদাহরণটিতে জিমেইল এপিআই-এর জন্য একটি সাধারণ আপলোড অনুরোধের ব্যবহার দেখানো হয়েছে।

POST /upload/gmail/v1/users/userId/messages/send?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: message/rfc822
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

Email Message data

অনুরোধটি সফল হলে, সার্ভার যেকোনো মেটাডেটা সহ HTTP 200 OK স্ট্যাটাস কোডটি ফেরত দেয়:

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

মাল্টিপার্ট আপলোড

আপলোড করার ডেটার সাথে যদি আপনি মেটাডেটাও পাঠাতে চান, তাহলে আপনি একটিমাত্র multipart/related রিকোয়েস্ট করতে পারেন। যদি আপনার পাঠানো ডেটার পরিমাণ এত কম হয় যে কানেকশন ব্যর্থ হলেও তা সম্পূর্ণভাবে আবার আপলোড করা সম্ভব, তবে এটি একটি ভালো উপায়।

মাল্টিপার্ট আপলোড ব্যবহার করতে, মেথডটির /upload URI-তে একটি POST বা PUT রিকোয়েস্ট পাঠান এবং uploadType=multipart কোয়েরি প্যারামিটারটি যোগ করুন, উদাহরণস্বরূপ:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=multipart

মাল্টিপার্ট আপলোড অনুরোধ করার সময় ব্যবহার করার জন্য শীর্ষ-স্তরের HTTP হেডারগুলো হলো:

• Content-Type কে multipart/related-এ সেট করুন এবং রিকোয়েস্টের অংশগুলো শনাক্ত করতে ব্যবহৃত বাউন্ডারি স্ট্রিংটি অন্তর্ভুক্ত করুন।
• Content-Length . অনুরোধের মূল অংশে থাকা মোট বাইট সংখ্যায় সেট করুন। অনুরোধের মিডিয়া অংশ অবশ্যই এই পদ্ধতির জন্য নির্দিষ্ট করা সর্বোচ্চ ফাইলের আকারের চেয়ে কম হতে হবে।

অনুরোধের মূল অংশটি একটি multipart/related কন্টেন্ট টাইপ [ RFC2387 ] হিসেবে ফরম্যাট করা হয় এবং এতে ঠিক দুটি অংশ থাকে। অংশ দুটি একটি বাউন্ডারি স্ট্রিং দ্বারা চিহ্নিত করা হয়, এবং চূড়ান্ত বাউন্ডারি স্ট্রিংটির পরে দুটি হাইফেন থাকে।

মাল্টিপার্ট রিকোয়েস্টের প্রতিটি অংশের জন্য একটি অতিরিক্ত Content-Type হেডার প্রয়োজন:

1. মেটাডেটা অংশ: এটি অবশ্যই প্রথমে আসতে হবে এবং Content-Type অবশ্যই স্বীকৃত মেটাডেটা ফরম্যাটগুলোর কোনো একটির সাথে মিলতে হবে।
2. মিডিয়া অংশ: এটি অবশ্যই দ্বিতীয় স্থানে আসতে হবে এবং Content-Type অবশ্যই মেথডটির স্বীকৃত মিডিয়া MIME টাইপগুলোর কোনো একটির সাথে মিলতে হবে।

প্রতিটি পদ্ধতির জন্য গৃহীত মিডিয়া MIME টাইপের তালিকা এবং আপলোড করা ফাইলের আকারের সীমা জানতে API রেফারেন্স দেখুন।

দ্রষ্টব্য: সংশ্লিষ্ট ডেটা আপলোড না করে শুধুমাত্র মেটাডেটা অংশ তৈরি বা আপডেট করতে, স্ট্যান্ডার্ড রিসোর্স এন্ডপয়েন্টে ( https://www.googleapis.com/gmail/v1/users/ userId /messages/send একটি POST বা PUT রিকোয়েস্ট পাঠান।

উদাহরণ: একাধিক অংশ আপলোড

নিচের উদাহরণটিতে জিমেইল এপিআই-এর জন্য একটি বহু-অংশযুক্ত আপলোড অনুরোধ দেখানো হয়েছে।

POST /upload/gmail/v1/users/userId/messages/send?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

--foo_bar_baz
Content-Type: message/rfc822

Email Message data
--foo_bar_baz--

অনুরোধটি সফল হলে, সার্ভার যেকোনো মেটাডেটা সহ HTTP 200 OK স্ট্যাটাস কোডটি ফেরত দেয়:

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

পুনরায় শুরুযোগ্য আপলোড

আরও নির্ভরযোগ্যভাবে ডেটা ফাইল আপলোড করার জন্য, আপনি রিজিউমেবল আপলোড প্রোটোকল ব্যবহার করতে পারেন। এই প্রোটোকলটি আপনাকে ডেটা প্রবাহে কোনো যোগাযোগ ব্যর্থতার কারণে বাধা সৃষ্টি হওয়ার পর আপলোড প্রক্রিয়াটি পুনরায় শুরু করার সুযোগ দেয়। এটি বিশেষত তখন উপযোগী যখন আপনি বড় ফাইল স্থানান্তর করছেন এবং নেটওয়ার্ক বাধা বা অন্য কোনো ট্রান্সমিশন ব্যর্থতার সম্ভাবনা বেশি থাকে, যেমন—মোবাইল ক্লায়েন্ট অ্যাপ থেকে আপলোড করার সময়। নেটওয়ার্ক ব্যর্থতার ক্ষেত্রে এটি আপনার ব্যান্ডউইথের ব্যবহারও কমাতে পারে, কারণ সেক্ষেত্রে আপনাকে বড় ফাইল আপলোড একেবারে শুরু থেকে পুনরায় শুরু করতে হয় না।

রিজিউমেবল আপলোড ব্যবহার করার ধাপগুলো হলো:

1. একটি পুনরায় শুরুযোগ্য সেশন চালু করুন । আপলোড URI-তে একটি প্রাথমিক অনুরোধ পাঠান, যাতে মেটাডেটা (যদি থাকে) অন্তর্ভুক্ত থাকবে।
2. পুনরায় শুরুযোগ্য সেশন ইউআরআই সংরক্ষণ করুন । প্রাথমিক অনুরোধের প্রতিক্রিয়ায় প্রাপ্ত সেশন ইউআরআইটি সংরক্ষণ করুন; এই সেশনের বাকি অনুরোধগুলোর জন্য আপনি এটি ব্যবহার করবেন।
3. ফাইলটি আপলোড করুন । মিডিয়া ফাইলটি রিস্যুমেবল সেশন ইউআরআই-তে পাঠান।

এছাড়াও, যে অ্যাপগুলো রিস্যুমেবল আপলোড ব্যবহার করে , সেগুলোতে মাঝপথে থেমে যাওয়া আপলোড পুনরায় শুরু করার জন্য কোড থাকা প্রয়োজন। যদি কোনো আপলোড মাঝপথে থেমে যায়, তবে কী পরিমাণ ডেটা সফলভাবে গৃহীত হয়েছে তা খুঁজে বের করুন এবং তারপর সেই বিন্দু থেকে আপলোডটি পুনরায় শুরু করুন।

দ্রষ্টব্য: একটি আপলোড URI এক সপ্তাহ পর মেয়াদোত্তীর্ণ হয়ে যায়।

ধাপ ১: পুনরায় শুরু করা যায় এমন একটি সেশন চালু করুন।

পুনরায় শুরুযোগ্য আপলোড শুরু করতে, মেথডটির /upload URI-তে একটি POST বা PUT রিকোয়েস্ট পাঠান এবং uploadType=resumable কোয়েরি প্যারামিটারটি যোগ করুন, উদাহরণস্বরূপ:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable

এই প্রাথমিক অনুরোধের ক্ষেত্রে, বডিটি হয় খালি থাকে অথবা এতে শুধু মেটাডেটা থাকে; আপনি যে ফাইলটি আপলোড করতে চান তার আসল বিষয়বস্তু পরবর্তী অনুরোধগুলোতে স্থানান্তর করবেন।

প্রাথমিক অনুরোধের সাথে নিম্নলিখিত HTTP হেডারগুলি ব্যবহার করুন:

• X-Upload-Content-Type . পরবর্তী অনুরোধগুলিতে স্থানান্তরিত করার জন্য আপলোড ডেটার মিডিয়া MIME টাইপে সেট করুন।
• X-Upload-Content-Length . পরবর্তী অনুরোধগুলিতে স্থানান্তরিত হওয়ার জন্য আপলোড ডেটার বাইট সংখ্যা নির্ধারণ করুন। এই অনুরোধের সময় যদি দৈর্ঘ্য অজানা থাকে, তবে আপনি এই হেডারটি বাদ দিতে পারেন।
• মেটাডেটা প্রদান করার ক্ষেত্রে: Content-Type . মেটাডেটার ডেটা টাইপ অনুযায়ী সেট করুন।
• Content-Length . এই প্রাথমিক অনুরোধের বডিতে প্রদত্ত বাইটের সংখ্যা অনুযায়ী সেট করুন। আপনি যদি chunked transfer encoding ব্যবহার করেন তবে এর প্রয়োজন নেই।

প্রতিটি পদ্ধতির জন্য গৃহীত মিডিয়া MIME টাইপের তালিকা এবং আপলোড করা ফাইলের আকারের সীমা জানতে API রেফারেন্স দেখুন।

উদাহরণ: পুনরায় শুরুযোগ্য সেশন শুরুর অনুরোধ

নিম্নলিখিত উদাহরণে দেখানো হয়েছে কিভাবে Gmail API-এর জন্য একটি পুনরায় শুরুযোগ্য সেশন শুরু করতে হয়।

POST /upload/gmail/v1/users/userId/messages/send?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: message/rfc822
X-Upload-Content-Length: 2000000

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

দ্রষ্টব্য: মেটাডেটা ছাড়া প্রাথমিক পুনঃশুরুযোগ্য আপডেট অনুরোধের জন্য, অনুরোধের বডি খালি রাখুন এবং Content-Length হেডারটি 0 -তে সেট করুন।

পরবর্তী অংশে প্রতিক্রিয়াটি কীভাবে সামলাতে হবে তা বর্ণনা করা হয়েছে।

ধাপ ২: পুনরায় শুরুযোগ্য সেশন URI সংরক্ষণ করুন।

সেশন শুরুর অনুরোধ সফল হলে, এপিআই সার্ভার একটি 200 OK HTTP স্ট্যাটাস কোড দিয়ে সাড়া দেয়। এছাড়াও, এটি একটি Location হেডার প্রদান করে যা আপনার পুনরায় শুরুযোগ্য সেশন URI নির্দিষ্ট করে। নিচের উদাহরণে দেখানো Location হেডারে একটি upload_id কোয়েরি প্যারামিটার অংশ অন্তর্ভুক্ত থাকে, যা এই সেশনের জন্য ব্যবহার করার অনন্য আপলোড আইডি প্রদান করে।

উদাহরণ: পুনরায় শুরুযোগ্য সেশন শুরুর প্রতিক্রিয়া

ধাপ ১-এর অনুরোধের প্রতিক্রিয়াটি হলো:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

উপরের উদাহরণ রেসপন্সে দেখানো Location হেডারের ভ্যালুটি হলো সেই সেশন URI, যা আপনি প্রকৃত ফাইল আপলোড করতে বা আপলোডের স্ট্যাটাস জানতে HTTP এন্ডপয়েন্ট হিসেবে ব্যবহার করবেন।

সেশন ইউআরআই-টি কপি করে সংরক্ষণ করুন, যাতে আপনি পরবর্তী অনুরোধগুলির জন্য এটি ব্যবহার করতে পারেন।

ধাপ ৩: ফাইলটি আপলোড করুন

ফাইলটি আপলোড করতে, পূর্ববর্তী ধাপে প্রাপ্ত আপলোড URI-তে একটি PUT রিকোয়েস্ট পাঠান। আপলোড রিকোয়েস্টের ফরম্যাটটি হলো:

PUT session_uri

পুনরায় শুরুযোগ্য ফাইল আপলোডের অনুরোধ করার সময় যে HTTP হেডারগুলো ব্যবহার করতে হয়, তার মধ্যে Content-Length অন্তর্ভুক্ত। এই অনুরোধে আপনি যে পরিমাণ বাইট আপলোড করছেন, সেই সংখ্যায় এটি সেট করুন, যা সাধারণত আপলোড ফাইলের আকার হয়ে থাকে।

উদাহরণ: পুনরায় শুরুযোগ্য ফাইল আপলোড অনুরোধ

বর্তমান উদাহরণের জন্য সম্পূর্ণ ২০,০০,০০০ বাইটের ইমেল বার্তা ফাইলটি আপলোড করার জন্য এখানে একটি পুনরায় শুরুযোগ্য অনুরোধ রয়েছে।

PUT https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: message/rfc822

bytes 0-1999999

অনুরোধটি সফল হলে, সার্ভার এই রিসোর্সের সাথে সম্পর্কিত যেকোনো মেটাডেটা সহ একটি HTTP 201 Created দিয়ে সাড়া দেয়। যদি রিস্যুমেবল সেশনের প্রাথমিক অনুরোধটি একটি বিদ্যমান রিসোর্স আপডেট করার জন্য একটি PUT অনুরোধ হয়ে থাকে, তাহলে সফলতার প্রতিক্রিয়া হবে 200 OK , এবং এর সাথে এই রিসোর্সের সাথে সম্পর্কিত যেকোনো মেটাডেটাও থাকবে।

যদি আপলোড অনুরোধটি বাধাগ্রস্ত হয় অথবা আপনি সার্ভার থেকে HTTP 503 Service Unavailable বা অন্য কোনো 5xx প্রতিক্রিয়া পান, তাহলে "resum an interrupted upload" অংশে বর্ণিত পদ্ধতি অনুসরণ করুন।

---

ফাইলটি খণ্ডে খণ্ডে আপলোড করা হচ্ছে

রিজিউমেবল আপলোডের মাধ্যমে, আপনি একটি ফাইলকে কয়েকটি খণ্ডে ভাগ করে প্রতিটি খণ্ড ক্রমানুসারে আপলোড করার জন্য একাধিক অনুরোধ পাঠাতে পারেন। এটি পছন্দের পদ্ধতি নয়, কারণ অতিরিক্ত অনুরোধগুলোর জন্য পারফরম্যান্সে খরচ হয় এবং সাধারণত এর প্রয়োজনও হয় না। তবে, যেকোনো একটি অনুরোধে স্থানান্তরিত ডেটার পরিমাণ কমাতে আপনার চাংকিং ব্যবহার করার প্রয়োজন হতে পারে। এটি তখন সহায়ক হয় যখন প্রতিটি অনুরোধের জন্য একটি নির্দিষ্ট সময়সীমা থাকে, যেমনটা গুগল অ্যাপ ইঞ্জিনের নির্দিষ্ট শ্রেণীর অনুরোধের ক্ষেত্রে দেখা যায়। এটি আপনাকে এমন সব পুরোনো ব্রাউজারের জন্য আপলোড অগ্রগতির ইঙ্গিত দেওয়ার মতো কাজও করতে দেয়, যেগুলোতে ডিফল্টভাবে আপলোড অগ্রগতির সাপোর্ট নেই।

আরও তথ্যের জন্য বিস্তারিত দেখুন

আপনি যদি ডেটা খণ্ড খণ্ড করে আপলোড করেন, তাহলে সম্পূর্ণ ফাইল আপলোডের জন্য প্রয়োজনীয় Content-Length হেডারের পাশাপাশি Content-Range হেডারটিও আবশ্যক:

• Content-Length . এটিকে চাঙ্ক সাইজের সমান অথবা তার চেয়ে কম সেট করুন, যেমনটি সর্বশেষ অনুরোধের ক্ষেত্রে হতে পারে।
• Content-Range : আপনি যে ফাইলটি আপলোড করছেন তার কোন বাইটগুলো দেখানো হবে তা সেট করতে পারেন। উদাহরণস্বরূপ, Content-Range: bytes 0-524287/2000000 দেখাচ্ছে যে আপনি একটি ২০,০০,০০০ বাইটের ফাইলের প্রথম ৫,২৪,২৮৮ বাইট (২৫৬ x ১০২৪ x ২) প্রদান করছেন।

চাঙ্ক সাইজের সীমাবদ্ধতা: আপলোড সম্পন্নকারী চূড়ান্ত চাঙ্কটি ছাড়া, সমস্ত চাঙ্কের আকার অবশ্যই ২৫৬ কিলোবাইট (২৫৬ x ১০২৪ বাইট)-এর গুণিতক হতে হবে। আপনি যদি চাঙ্কিং ব্যবহার করেন, তবে আপলোডকে কার্যকর রাখতে চাঙ্কের আকার যথাসম্ভব বড় রাখা গুরুত্বপূর্ণ।

উদাহরণ: পুনরায় শুরুযোগ্য খণ্ডিত ফাইল আপলোড অনুরোধ

যে অনুরোধে প্রথম ৫২৪,২৮৮ বাইট পাঠানো হয়, সেটি দেখতে এইরকম হতে পারে:

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: message/rfc822
Content-Range: bytes 0-524287/2000000

bytes 0-524288

অনুরোধটি সফল হলে, সার্ভার 308 Resume Incomplete দিয়ে সাড়া দেয় এবং এর সাথে একটি Range হেডার যুক্ত করে, যা এখন পর্যন্ত সংরক্ষিত মোট বাইটের সংখ্যা শনাক্ত করে।

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

পরবর্তী অংশটি কোথা থেকে শুরু করতে হবে তা নির্ধারণ করতে Range হেডারে প্রাপ্ত সর্বোচ্চ মানটি ব্যবহার করুন। সম্পূর্ণ ফাইলটি আপলোড না হওয়া পর্যন্ত ফাইলের প্রতিটি অংশ PUT থাকুন।

যদি কোনো চাঙ্কের PUT অনুরোধ বাধাগ্রস্ত হয় অথবা আপনি সার্ভার থেকে HTTP 503 Service Unavailable বা অন্য কোনো 5xx প্রতিক্রিয়া পান, তাহলে 'resum an interrupted upload' অংশে বর্ণিত পদ্ধতি অনুসরণ করুন, কিন্তু ফাইলের বাকি অংশ আপলোড করার পরিবর্তে, কেবল সেই বিন্দু থেকে চাঙ্কগুলো আপলোড করা চালিয়ে যান।

গুরুত্বপূর্ণ নোট:

• পরবর্তী অংশটি কোথা থেকে শুরু করতে হবে তা নির্ধারণ করতে রেসপন্সে অবশ্যই Range হেডার ব্যবহার করুন; আগের অনুরোধে পাঠানো সমস্ত বাইট সার্ভার পেয়েছে বলে ধরে নেবেন না।
• প্রতিটি আপলোড URI-এর একটি নির্দিষ্ট মেয়াদ থাকে এবং অবশেষে তা শেষ হয়ে যায় (ব্যবহৃত না হলে প্রায় একদিনের মধ্যে)। এই কারণে, পুনরায় শুরুযোগ্য আপলোডটি আপলোড URI পাওয়ার সাথে সাথেই শুরু করা এবং বাধাগ্রস্ত হওয়ার কিছুক্ষণ পরেই মাঝপথে থেমে যাওয়া আপলোডটি পুনরায় শুরু করা সবচেয়ে ভালো।
• যদি আপনি একটি মেয়াদোত্তীর্ণ আপলোড সেশন আইডি দিয়ে অনুরোধ পাঠান, তাহলে সার্ভার একটি 404 Not Found স্ট্যাটাস কোড ফেরত দেয়। যখন আপলোড সেশনে একটি অপূরণীয় ত্রুটি ঘটে, তখন সার্ভার একটি 410 Gone স্ট্যাটাস কোড ফেরত দেয়। এইসব ক্ষেত্রে, আপনাকে অবশ্যই একটি নতুন রিজিউমেবল আপলোড শুরু করতে হবে, একটি নতুন আপলোড ইউআরআই সংগ্রহ করতে হবে এবং নতুন এন্ডপয়েন্টটি ব্যবহার করে শুরু থেকে আপলোডটি শুরু করতে হবে।

সম্পূর্ণ ফাইল আপলোড সম্পন্ন হলে, সার্ভার এই রিসোর্সের সাথে যুক্ত যেকোনো মেটাডেটা সহ একটি HTTP 201 Created রেসপন্স পাঠায়। যদি এই অনুরোধটি নতুন কিছু তৈরি করার পরিবর্তে বিদ্যমান কোনো এনটিটি আপডেট করার জন্য করা হতো, তাহলে আপলোড সম্পন্ন হওয়ার জন্য HTTP রেসপন্স কোডটি 200 OK হতো।

---

বাধাগ্রস্ত আপলোড পুনরায় শুরু করুন

যদি কোনো প্রতিক্রিয়া পাওয়ার আগেই আপলোড অনুরোধটি বন্ধ হয়ে যায় অথবা আপনি সার্ভার থেকে HTTP 503 Service Unavailable প্রতিক্রিয়া পান, তাহলে আপনাকে বাধাগ্রস্ত আপলোডটি পুনরায় শুরু করতে হবে। এটি করার জন্য:

1. স্ট্যাটাস জানতে অনুরোধ করুন। আপলোড URI-তে একটি খালি PUT অনুরোধ পাঠিয়ে আপলোডের বর্তমান স্ট্যাটাস সম্পর্কে জানুন। এই অনুরোধের জন্য, HTTP হেডারে একটি Content-Range হেডার অন্তর্ভুক্ত করা উচিত, যা নির্দেশ করে যে ফাইলের বর্তমান অবস্থান অজানা। উদাহরণস্বরূপ, যদি আপনার ফাইলের মোট দৈর্ঘ্য ২,০০০,০০০ হয়, তাহলে Content-Range কে */2000000 সেট করুন। যদি আপনি ফাইলের সম্পূর্ণ আকার না জানেন, তাহলে Content-Range কে */* সেট করুন।

   দ্রষ্টব্য: আপনি শুধু আপলোড বাধাগ্রস্ত হলেই নয়, বরং প্রতিটি খণ্ডের মাঝেও স্ট্যাটাস জানতে চাইতে পারেন। উদাহরণস্বরূপ, আপনি যদি পুরোনো ব্রাউজারগুলোর জন্য আপলোডের অগ্রগতির ইঙ্গিত দেখাতে চান, তবে এটি বেশ কার্যকর।

2. আপলোড করা বাইটের সংখ্যা জানুন। স্ট্যাটাস কোয়েরি থেকে প্রাপ্ত প্রতিক্রিয়াটি প্রসেস করুন। সার্ভার তার প্রতিক্রিয়ায় Range হেডার ব্যবহার করে নির্দিষ্ট করে যে, সে এখন পর্যন্ত কোন বাইটগুলো পেয়েছে। উদাহরণস্বরূপ, 0-299999 রেঞ্জের একটি Range হেডার নির্দেশ করে যে ফাইলটির প্রথম 300,000 বাইট গ্রহণ করা হয়েছে।
3. অবশিষ্ট ডেটা আপলোড করুন। অবশেষে, এখন যেহেতু আপনি জানেন কোথা থেকে অনুরোধটি পুনরায় শুরু করতে হবে, তাই অবশিষ্ট ডেটা বা বর্তমান চাঙ্কটি পাঠান। মনে রাখবেন, উভয় ক্ষেত্রেই আপনাকে অবশিষ্ট ডেটাকে একটি পৃথক চাঙ্ক হিসাবে বিবেচনা করতে হবে, তাই আপলোড পুনরায় শুরু করার সময় আপনাকে Content-Range হেডারটি পাঠাতে হবে।

উদাহরণ: বাধাগ্রস্ত আপলোড পুনরায় শুরু করা

১) আপলোডের অবস্থা জানতে অনুরোধ করুন।

নিম্নলিখিত অনুরোধটি Content-Range হেডার ব্যবহার করে এটি নির্দেশ করে যে ২০,০০,০০০ বাইটের ফাইলটিতে বর্তমান অবস্থানটি অজানা।

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

২) রেসপন্স থেকে এখন পর্যন্ত আপলোড হওয়া বাইটের সংখ্যা বের করুন।

সার্ভারের প্রতিক্রিয়াটি Range হেডার ব্যবহার করে নির্দেশ করে যে এটি এখন পর্যন্ত ফাইলটির প্রথম ৪৩ বাইট পেয়েছে। পুনরায় শুরু হওয়া আপলোডটি কোথা থেকে শুরু করতে হবে তা নির্ধারণ করতে Range হেডারের ঊর্ধ্বসীমা ব্যবহার করুন।

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

দ্রষ্টব্য: আপলোড সম্পূর্ণ হলে স্ট্যাটাস রেসপন্স 201 Created বা 200 OK হতে পারে। সমস্ত বাইট আপলোড হওয়ার পর কিন্তু ক্লায়েন্ট সার্ভার থেকে রেসপন্স পাওয়ার আগে যদি সংযোগ বিচ্ছিন্ন হয়ে যায়, তবে এমনটা হতে পারে।

৩) যেখান থেকে আপলোডটি থেমেছিল, সেখান থেকে আবার শুরু করুন।

নিম্নলিখিত অনুরোধটি ৪৩ নম্বর বাইট থেকে শুরু করে ফাইলের অবশিষ্ট বাইটগুলো পাঠানোর মাধ্যমে আপলোড পুনরায় শুরু করে।

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

সর্বোত্তম অনুশীলন

মিডিয়া আপলোড করার সময় ত্রুটি ব্যবস্থাপনা সম্পর্কিত কিছু উত্তম অনুশীলন সম্পর্কে সচেতন থাকা সহায়ক।

• সংযোগ বিচ্ছিন্ন হওয়া বা যেকোনো 5xx ত্রুটির কারণে ব্যর্থ হওয়া আপলোডগুলি পুনরায় শুরু করুন বা আবার চেষ্টা করুন, যার মধ্যে অন্তর্ভুক্ত রয়েছে:
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout
• আপলোড অনুরোধ পুনরায় শুরু করতে বা চেষ্টা করার সময় কোনো 5xx সার্ভার ত্রুটি দেখা দিলে একটি এক্সপোনেনশিয়াল ব্যাকঅফ কৌশল ব্যবহার করুন। কোনো সার্ভার ওভারলোডেড হয়ে গেলে এই ত্রুটিগুলো ঘটতে পারে। বিপুল সংখ্যক অনুরোধ বা ভারী নেটওয়ার্ক ট্র্যাফিকের সময় এক্সপোনেনশিয়াল ব্যাকঅফ এই ধরনের সমস্যাগুলো কমাতে সাহায্য করতে পারে।
• অন্যান্য ধরনের অনুরোধ এক্সপোনেনশিয়াল ব্যাকঅফ দ্বারা পরিচালনা করা উচিত নয়, তবে আপনি সেগুলোর বেশ কয়েকটি পুনরায় চেষ্টা করতে পারেন। এই অনুরোধগুলো পুনরায় চেষ্টা করার সময়, চেষ্টার সংখ্যা সীমিত করুন। উদাহরণস্বরূপ, আপনার কোড একটি ত্রুটি জানানোর আগে দশবার বা তার কমবার পুনরায় চেষ্টা করার মধ্যে সীমাবদ্ধ রাখতে পারে।
• পুনরায় শুরুযোগ্য আপলোড করার সময় সম্পূর্ণ আপলোড প্রক্রিয়াটি শুরু থেকে আবার শুরু করে 404 Not Found এবং 410 Gone ত্রুটিগুলি সমাধান করুন।

সূচকীয় ব্যাকঅফ

এক্সপোনেনশিয়াল ব্যাকঅফ হলো নেটওয়ার্ক অ্যাপ্লিকেশনগুলির জন্য একটি আদর্শ ত্রুটি পরিচালনা কৌশল, যেখানে ক্লায়েন্ট ক্রমবর্ধমান সময় ধরে পর্যায়ক্রমে একটি ব্যর্থ অনুরোধ পুনরায় চেষ্টা করে। যদি বিপুল সংখ্যক অনুরোধ বা ভারী নেটওয়ার্ক ট্র্যাফিকের কারণে সার্ভার ত্রুটি দেখায়, তবে সেই ত্রুটিগুলি পরিচালনা করার জন্য এক্সপোনেনশিয়াল ব্যাকঅফ একটি ভালো কৌশল হতে পারে। অন্যদিকে, নেটওয়ার্কের পরিমাণ বা প্রতিক্রিয়ার সময়ের সাথে সম্পর্কহীন ত্রুটি, যেমন—অবৈধ অনুমোদন ক্রেডেনশিয়াল বা ফাইল খুঁজে না পাওয়ার মতো ত্রুটি মোকাবেলার জন্য এটি একটি প্রাসঙ্গিক কৌশল নয়।

সঠিকভাবে ব্যবহার করা হলে, এক্সপোনেনশিয়াল ব্যাকঅফ ব্যান্ডউইথ ব্যবহারের দক্ষতা বাড়ায়, সফল প্রতিক্রিয়া পাওয়ার জন্য প্রয়োজনীয় অনুরোধের সংখ্যা কমায় এবং যুগপৎ কার্যপরিবেশে অনুরোধের থ্রুপুট সর্বাধিক করে তোলে।

সরল এক্সপোনেনশিয়াল ব্যাকঅফ বাস্তবায়নের প্রক্রিয়াটি নিম্নরূপ:

1. এপিআই-তে একটি অনুরোধ পাঠান।
2. একটি HTTP 503 প্রতিক্রিয়া পাওয়া গেছে, যার অর্থ হলো অনুরোধটি পুনরায় চেষ্টা করা উচিত।
3. ১ সেকেন্ড + random_number_milliseconds অপেক্ষা করুন এবং অনুরোধটি পুনরায় চেষ্টা করুন।
4. একটি HTTP 503 প্রতিক্রিয়া পাওয়া গেছে, যার অর্থ হলো অনুরোধটি পুনরায় চেষ্টা করা উচিত।
5. ২ সেকেন্ড + random_number_milliseconds অপেক্ষা করুন এবং অনুরোধটি পুনরায় চেষ্টা করুন।
6. একটি HTTP 503 প্রতিক্রিয়া পাওয়া গেছে, যার অর্থ হলো অনুরোধটি পুনরায় চেষ্টা করা উচিত।
7. ৪ সেকেন্ড + random_number_milliseconds অপেক্ষা করুন এবং অনুরোধটি পুনরায় চেষ্টা করুন।
8. একটি HTTP 503 প্রতিক্রিয়া পাওয়া গেছে, যার অর্থ হলো অনুরোধটি পুনরায় চেষ্টা করা উচিত।
9. ৮ সেকেন্ড + random_number_milliseconds অপেক্ষা করুন এবং অনুরোধটি পুনরায় চেষ্টা করুন।
10. একটি HTTP 503 প্রতিক্রিয়া পাওয়া গেছে, যার অর্থ হলো অনুরোধটি পুনরায় চেষ্টা করা উচিত।
11. ১৬ সেকেন্ড + random_number_milliseconds অপেক্ষা করুন এবং অনুরোধটি পুনরায় চেষ্টা করুন।
12. থামুন। ত্রুটি রিপোর্ট করুন বা নথিভুক্ত করুন।

উপরের ফ্লো-তে, random_number_milliseconds হলো ১০০০ বা তার কম মিলিসেকেন্ডের একটি র‍্যান্ডম সংখ্যা। এটি প্রয়োজনীয়, কারণ একটি ছোট র‍্যান্ডম ডিলে যোগ করলে লোড আরও সুষমভাবে বণ্টিত হয় এবং সার্ভারে অতিরিক্ত চাপ সৃষ্টি হওয়ার সম্ভাবনা এড়ানো যায়। প্রতিটি অপেক্ষার পর random_number_milliseconds-এর মান পুনরায় নির্ধারণ করতে হবে।

দ্রষ্টব্য: অপেক্ষার সময় সর্বদা (2 ^ n) + random_number_milliseconds, যেখানে n হলো একটি একমুখী ক্রমবর্ধমান পূর্ণসংখ্যা যা প্রাথমিকভাবে 0 হিসাবে সংজ্ঞায়িত। প্রতিটি পুনরাবৃত্তির (প্রতিটি অনুরোধের) জন্য পূর্ণসংখ্যা n-কে 1 করে বাড়ানো হয়।

অ্যালগরিদমটি n-এর মান ৫ হলে বন্ধ হওয়ার জন্য সেট করা আছে। এই সর্বোচ্চ সীমা ক্লায়েন্টদের অনির্দিষ্টকাল ধরে পুনরায় চেষ্টা করা থেকে বিরত রাখে এবং এর ফলে একটি অনুরোধকে "অপ্রতিরোধ্য ত্রুটি" হিসেবে গণ্য করার আগে মোট প্রায় ৩২ সেকেন্ডের বিলম্ব হয়। পুনরায় চেষ্টার সর্বোচ্চ সংখ্যা আরও বেশি হলেও সমস্যা নেই, বিশেষ করে যদি একটি দীর্ঘ আপলোড প্রক্রিয়া চলমান থাকে; শুধু খেয়াল রাখতে হবে যেন পুনরায় চেষ্টার বিলম্ব একটি যুক্তিসঙ্গত সীমার মধ্যে সীমাবদ্ধ থাকে, যেমন—এক মিনিটের কম।

এপিআই ক্লায়েন্ট লাইব্রেরি নির্দেশিকা

• .NET
• জাভা
• পিএইচপি
• পাইথন
• রুবি