Eric Bidelman จากทีม G Suite API
กุมภาพันธ์ 2010
บทนำ
มาตรฐานเว็บในปัจจุบันไม่มีกลไกที่เชื่อถือได้ในการอํานวยความสะดวกให้การอัปโหลด HTTP ของไฟล์ขนาดใหญ่ ผลที่ตามมาคือโดยทั่วไปแล้วการอัปโหลดไฟล์ที่ Google และเว็บไซต์อื่นๆ มีการจํากัดขนาดปานกลาง (เช่น 100 MB) สําหรับบริการอย่าง YouTube และ Google List List API ซึ่งรองรับการอัปโหลดไฟล์ขนาดใหญ่ นี่จะเป็นอุปสรรคสําคัญ
โปรโตคอลที่กลับมาทํางานอีกครั้งของ Google จะช่วยแก้ปัญหาที่กล่าวถึงข้างต้นได้โดยตรงด้วยการรองรับคําขอ HTTP POST/PUT ที่กลับมาทํางานอีกครั้งใน HTTP/1.0 โปรโตคอลนี้สร้างโมเดลโดยอิงตาม ResumableHttpRequestsOffer ที่ทีม Googleเฟืองแนะนํา
เอกสารนี้อธิบายวิธีรวมฟีเจอร์การอัปโหลดที่กลับมาทํางานอีกครั้งของ Google Data ลงในแอปพลิเคชันของคุณ ตัวอย่างด้านล่างใช้ Data API สําหรับรายการเอกสารของ Google โปรดทราบว่า API อื่นๆ ของ Google ที่ใช้โปรโตคอลนี้อาจมีข้อกําหนด/โค้ดการตอบกลับ/อื่นๆ ต่างกันเล็กน้อย โปรดดูเอกสารเฉพาะของบริการนั้นๆ
โปรโตคอลที่กลับมาทํางานอีกครั้งได้
การเริ่มต้นคําขออัปโหลดที่กลับมาทํางานอีกครั้ง
หากต้องการเริ่มเซสชันการอัปโหลดที่กลับมาทํางานอีกครั้ง ให้ส่งคําขอ HTTP POST
ไปยังลิงก์โพสต์ต่อที่กลับมาทํางานอีกครั้ง ลิงก์นี้จะอยู่ที่ระดับฟีด
ลิงก์โพสต์ที่เผยแพร่ต่อของ DocList API มีลักษณะดังนี้
<link rel="http://schemas.google.com/g/2005#resumable-create-media" type="application/atom+xml" href="https://docs.google.com/feeds/upload/create-session/default/private/full"/>
เนื้อหาของคําขอ POST
ควรว่างเปล่าหรือมีรายการ Atom XML และต้องไม่รวมเนื้อหาในไฟล์จริง
ตัวอย่างด้านล่างสร้างคําขอที่กลับมาทํางานอีกครั้งเพื่ออัปโหลดไฟล์ PDF ขนาดใหญ่ และระบุชื่อเอกสารในอนาคตโดยใช้ส่วนหัว Slug
POST /feeds/upload/create-session/default/private/full HTTP/1.1 Host: docs.google.com GData-Version: version_number Authorization: authorization Content-Length: 0 Slug: MyTitle X-Upload-Content-Type: content_type X-Upload-Content-Length: content_length empty body
ส่วนหัว X-Upload-Content-Type
และ X-Upload-Content-Length
ควรตั้งค่าเป็น Mimetype และขนาดของไฟล์ที่จะอัปโหลดในที่สุด หากไม่ทราบความยาวของเนื้อหาเมื่อสร้างเซสชันการอัปโหลด ระบบอาจไม่สนใจส่วนหัว X-Upload-Content-Length
นี่คือตัวอย่างคําขออื่นที่อัปโหลดเอกสารคําแทน ครั้งนี้จะรวมอยู่ในข้อมูลเมตาของ Atom และจะใช้กับรายการเอกสารสุดท้าย
POST /feeds/upload/create-session/default/private/full?convert=false HTTP/1.1
Host: docs.google.com
GData-Version: version_number
Authorization: authorization
Content-Length: atom_metadata_content_length
Content-Type: application/atom+xml
X-Upload-Content-Type: application/msword
X-Upload-Content-Length: 7654321
<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:docs="http://schemas.google.com/docs/2007">
<category scheme="http://schemas.google.com/g/2005#kind"
term="http://schemas.google.com/docs/2007#document"/>
<title>MyTitle</title>
<docs:writersCanInvite value="false"/>
</entry>
การตอบกลับของเซิร์ฟเวอร์จาก POST
เริ่มต้นคือ URI การอัปโหลดที่ไม่ซ้ําในส่วนหัว Location
และเนื้อความการตอบกลับที่ว่างเปล่า:
HTTP/1.1 200 OK
Location: <upload_uri>
ระบบจะใช้ URI การอัปโหลดที่ไม่ซ้ํากันในการอัปโหลดไฟล์กลุ่ม
หมายเหตุ: คําขอ POST
เริ่มต้นจะไม่สร้างรายการใหม่ในฟีด
ซึ่งจะเกิดขึ้นเมื่อการอัปโหลดเสร็จสมบูรณ์ทั้งหมดเท่านั้น
หมายเหตุ: URI ของเซสชันที่กลับมาทํางานอีกครั้งจะหมดอายุหลังจากผ่านไป 1 สัปดาห์
การอัปโหลดไฟล์
โปรโตคอลที่กลับมาทํางานต่อได้ (แต่ไม่บังคับ) ให้อัปโหลดเนื้อหาใน "กลุ่ม" เนื่องจากไม่มี HTTP เกี่ยวกับขนาดคําขอ ลูกค้าของคุณสามารถเลือกขนาดไฟล์เป็นส่วนๆ หรือเพียงแค่อัปโหลดไฟล์ทั้งหมดก็ได้
ตัวอย่างนี้ใช้ URI การอัปโหลดที่ไม่ซ้ํากันเพื่อออก PUT
กลับมาทํางานอีกครั้ง ตัวอย่างต่อไปนี้จะส่งไฟล์ 1234567 ไบต์ PDF ขนาด 100,000 ไบต์แรก
PUT upload_uri HTTP/1.1 Host: docs.google.com Content-Length: 100000 Content-Range: bytes 0-99999/1234567 bytes 0-99999
หากไม่ทราบขนาดของไฟล์ PDF ตัวอย่างนี้จะใช้ Content-Range: bytes
0-99999/*
อ่านข้อมูลเพิ่มเติมเกี่ยวกับส่วนหัว Content-Range
ได้ที่นี่
เซิร์ฟเวอร์จะตอบสนองด้วยช่วงไบต์ปัจจุบันที่จัดเก็บไว้:
HTTP/1.1 308 Resume Incomplete Content-Length: 0 Range: bytes=0-99999
ไคลเอ็นต์ควรPUT
ไฟล์แต่ละกลุ่มต่อไปจนกว่าจะมีการอัปโหลดไฟล์ทั้งหมด
เซิร์ฟเวอร์จะตอบกลับด้วย HTTP 308 Resume Incomplete
และช่วงไบต์ที่รู้จักในส่วนหัว Range
จนกว่าการอัปโหลดจะเสร็จสมบูรณ์ ไคลเอ็นต์ต้องใช้ส่วนหัว Range
เพื่อกําหนดตําแหน่งที่จะเริ่มกลุ่มถัดไป
ดังนั้น อย่าสมมติว่าเซิร์ฟเวอร์ได้รับไบต์ทั้งหมดที่ส่งตั้งแต่แรกในคําขอ PUT
หมายเหตุ: เซิร์ฟเวอร์อาจส่ง URI การอัปโหลดใหม่ที่ไม่ซ้ําในส่วนหัว Location
ระหว่างกลุ่มข้อมูล ไคลเอ็นต์ควรตรวจหา Location
ที่อัปเดตและใช้ URI ดังกล่าวเพื่อส่งกลุ่มที่เหลือไปยังเซิร์ฟเวอร์
เมื่อการอัปโหลดเสร็จสมบูรณ์ การตอบกลับจะเป็นไปในลักษณะเดียวกับการอัปโหลดโดยใช้กลไกการอัปโหลดที่ไม่กลับมาทํางานอีกครั้งของ API กล่าวคือ ระบบจะแสดงผล 201 Created
พร้อมกับ <atom:entry>
ที่เซิร์ฟเวอร์สร้างขึ้น PUT
ที่ตามมาของ URI การอัปโหลดที่ไม่ซ้ําจะแสดงการตอบกลับเดียวกันกับสิ่งที่ส่งคืนเมื่อการอัปโหลดเสร็จสมบูรณ์
หลังจากผ่านไประยะหนึ่ง การตอบกลับจะเป็น 410 Gone
หรือ 404 Not Found
อัปโหลดต่อ
หากคําขอสิ้นสุดลงก่อนได้รับการตอบกลับจากเซิร์ฟเวอร์หรือคุณได้รับการตอบสนอง HTTP 503
จากเซิร์ฟเวอร์ คุณจะค้นหาสถานะปัจจุบันของการอัปโหลดได้โดยส่งคําขอ PUT
ที่ว่างเปล่าบน URI การอัปโหลดที่ไม่ซ้ํา
ไคลเอ็นต์จะสํารวจเซิร์ฟเวอร์เพื่อระบุว่าไบต์ใดที่ได้รับ
PUT upload_uri HTTP/1.1 Host: docs.google.com Content-Length: 0 Content-Range: bytes */content_length
ใช้ *
เป็น content_length หากไม่ทราบความยาว
เซิร์ฟเวอร์ตอบสนองด้วยช่วงไบต์ปัจจุบัน:
HTTP/1.1 308 Resume Incomplete Content-Length: 0 Range: bytes=0-42
หมายเหตุ: หากเซิร์ฟเวอร์ไม่ได้คอมมิตไบต์ใดๆ สําหรับเซสชัน เซิร์ฟเวอร์นี้จะไม่มีส่วนหัว Range
หมายเหตุ: เซิร์ฟเวอร์อาจส่ง URI การอัปโหลดใหม่ที่ไม่ซ้ําในส่วนหัว Location
ระหว่างกลุ่มข้อมูล ไคลเอ็นต์ควรตรวจหา Location
ที่อัปเดตและใช้ URI ดังกล่าวเพื่อส่งกลุ่มที่เหลือไปยังเซิร์ฟเวอร์
สุดท้าย ไคลเอ็นต์จะกลับมาทํางานอีกครั้งต่อจากจุดที่เซิร์ฟเวอร์ค้างไว้ ดังนี้
PUT upload_uri HTTP/1.1 Host: docs.google.com Content-Length: 57 Content-Range: 43-99/100 <bytes 43-99>
การยกเลิกการอัปโหลด
หากต้องการยกเลิกการอัปโหลดและป้องกันไม่ให้มีการดําเนินการเพิ่มเติม โปรดส่งคําขอ DELETE
ใน URI การอัปโหลดที่ไม่ซ้ํา
DELETE upload_uri HTTP/1.1 Host: docs.google.com Content-Length: 0
หากสําเร็จ เซิร์ฟเวอร์จะตอบว่าเซสชันถูกยกเลิก และตอบสนองด้วยโค้ดเดียวกันสําหรับ PUT
หรือ คําขอสถานะการค้นหา เพิ่มเติม
HTTP/1.1 499 Client Closed Request
หมายเหตุ: หากการอัปโหลดถูกยกเลิกโดยไม่ยกเลิก โดยปกติการอัปโหลดจะหมดอายุภายใน 1 สัปดาห์หลังจากที่สร้าง
การอัปเดตทรัพยากรที่มีอยู่
เช่นเดียวกับการเริ่มต้นเซสชันการอัปโหลดที่กลับมาทํางานอีกครั้ง คุณสามารถใช้โปรโตคอลการอัปโหลดที่กลับมาทํางานอีกครั้งได้เพื่อแทนที่เนื้อหาของไฟล์ที่มีอยู่ หากต้องการเริ่มคําขออัปเดตที่กลับมาทํางานอีกครั้ง ให้ส่ง HTTP PUT
ไปยังลิงก์ของรายการด้วย rel='...#resumable-edit-media
'
สื่อแต่ละรายการ entry
จะมีลิงก์ดังกล่าวหาก API รองรับการอัปเดตเนื้อหาของทรัพยากร
ตัวอย่างเช่น รายการเอกสารใน DocList API จะมีลิงก์ที่คล้ายกับสิ่งต่อไปนี้
<link rel="http://schemas.google.com/g/2005#resumable-edit-media" type="application/atom+xml" href="https://docs.google.com/feeds/upload/create-session/default/private/full/document%3A12345"/>
ดังนั้นคําขอเริ่มต้นจึงเป็น
PUT /feeds/upload/create-session/default/private/full/document%3A12345 HTTP/1.1 Host: docs.google.com GData-Version: version_number Authorization: authorization If-Match: ETag | * Content-Length: 0 X-Upload-Content-Length: content_length X-Upload-Content-Type: content_type empty body
หากต้องการอัปเดตข้อมูลเมตาและเนื้อหาในเวลาเดียวกัน ให้ใส่ Atom XML แทนเนื้อความที่ว่างเปล่า ดูตัวอย่างในส่วนการเริ่มต้นคําขออัปโหลดที่กลับมาทํางานอีกครั้ง
เมื่อเซิร์ฟเวอร์ตอบสนองด้วย URI การอัปโหลดที่ไม่ซ้ํา ให้ส่ง PUT
ด้วยเพย์โหลด เมื่อคุณมี URI การอัปโหลดที่ไม่ซ้ํากันแล้ว กระบวนการอัปเดตเนื้อหาของไฟล์จะเหมือนกับการอัปโหลดไฟล์
ตัวอย่างนี้จะอัปเดตเนื้อหาของเอกสารที่มีอยู่ในมุมมองเดียว
PUT upload_uri HTTP/1.1 Host: docs.google.com Content-Length: 1000 Content-Range: 0-999/1000 <bytes 0-999>
ตัวอย่างไลบรารีของไคลเอ็นต์
ด้านล่างคือตัวอย่างการอัปโหลดไฟล์ภาพยนตร์ไปยัง Google เอกสาร (โดยใช้โปรโตคอลการอัปโหลดที่กลับมาทํางานอีกครั้ง) ในไลบรารีของไคลเอ็นต์ Google Data โปรดทราบว่าห้องสมุดบางแห่งไม่รองรับฟีเจอร์กลับมาทํางานอีกครั้งในขณะนี้
int MAX_CONCURRENT_UPLOADS = 10; int PROGRESS_UPDATE_INTERVAL = 1000; int DEFAULT_CHUNK_SIZE = 10485760; DocsService client = new DocsService("yourCompany-yourAppName-v1"); client.setUserCredentials("user@gmail.com", "pa$$word"); // Create a listener FileUploadProgressListener listener = new FileUploadProgressListener(); // See the sample for details on this class. // Pool for handling concurrent upload tasks ExecutorService executor = Executors.newFixedThreadPool(MAX_CONCURRENT_UPLOADS); // Create {@link ResumableGDataFileUploader} for each file to upload Listuploaders = Lists.newArrayList(); File file = new File("test.mpg"); String contentType = DocumentListEntry.MediaType.fromFileName(file.getName()).getMimeType(); MediaFileSource mediaFile = new MediaFileSource(file, contentType); URL createUploadUrl = new URL("https://docs.google.com/feeds/upload/create-session/default/private/full"); ResumableGDataFileUploader uploader = new ResumableGDataFileUploader(createUploadUrl, mediaFile, client, DEFAULT_CHUNK_SIZE, executor, listener, PROGRESS_UPDATE_INTERVAL); uploaders.add(uploader); listener.listenTo(uploaders); // attach the listener to list of uploaders // Start the upload(s) for (ResumableGDataFileUploader uploader : uploaders) { uploader.start(); } // wait for uploads to complete while(!listener.isDone()) { try { Thread.sleep(100); } catch (InterruptedException ie) { listener.printResults(); throw ie; // rethrow }
// Chunk size in MB int CHUNK_SIZE = 1; ClientLoginAuthenticator cla = new ClientLoginAuthenticator( "yourCompany-yourAppName-v1", ServiceNames.Documents, "user@gmail.com", "pa$$word"); // Set up resumable uploader and notifications ResumableUploader ru = new ResumableUploader(CHUNK_SIZE); ru.AsyncOperationCompleted += new AsyncOperationCompletedEventHandler(this.OnDone); ru.AsyncOperationProgress += new AsyncOperationProgressEventHandler(this.OnProgress); // Set metadata for our upload. Document entry = new Document() entry.Title = "My Video"; entry.MediaSource = new MediaFileSource("c:\\test.mpg", "video/mpeg"); // Add the upload uri to document entry. Uri createUploadUrl = new Uri("https://docs.google.com/feeds/upload/create-session/default/private/full"); AtomLink link = new AtomLink(createUploadUrl.AbsoluteUri); link.Rel = ResumableUploader.CreateMediaRelation; entry.DocumentEntry.Links.Add(link); ru.InsertAsync(cla, entry.DocumentEntry, userObject);
- (void)uploadAFile { NSString *filePath = @"~/test.mpg"; NSString *fileName = [filePath lastPathComponent]; // get the file's data NSData *data = [NSData dataWithContentsOfMappedFile:filePath]; // create an entry to upload GDataEntryDocBase *newEntry = [GDataEntryStandardDoc documentEntry]; [newEntry setTitleWithString:fileName]; [newEntry setUploadData:data]; [newEntry setUploadMIMEType:@"video/mpeg"]; [newEntry setUploadSlug:fileName]; // to upload, we need the entry, our service object, the upload URL, // and the callback for when upload has finished GDataServiceGoogleDocs *service = [self docsService]; NSURL *uploadURL = [GDataServiceGoogleDocs docsUploadURL]; SEL finishedSel = @selector(uploadTicket:finishedWithEntry:error:); // now start the upload GDataServiceTicket *ticket = [service fetchEntryByInsertingEntry:newEntry forFeedURL:uploadURL delegate:self didFinishSelector:finishedSel]; // progress monitoring is done by specifying a callback, like this SEL progressSel = @selector(ticket:hasDeliveredByteCount:ofTotalByteCount:); [ticket setUploadProgressSelector:progressSel]; } // callback for when uploading has finished - (void)uploadTicket:(GDataServiceTicket *)ticket finishedWithEntry:(GDataEntryDocBase *)entry error:(NSError *)error { if (error == nil) { // upload succeeded } } - (void)pauseOrResumeUploadForTicket:(GDataServiceTicket *)ticket { if ([ticket isUploadPaused]) { [ticket resumeUpload]; } else { [ticket pauseUpload]; } }
import os.path import atom.data import gdata.client import gdata.docs.client import gdata.docs.data CHUNK_SIZE = 10485760 client = gdata.docs.client.DocsClient(source='yourCompany-yourAppName-v1') client.ClientLogin('user@gmail.com', 'pa$$word', client.source); f = open('test.mpg') file_size = os.path.getsize(f.name) uploader = gdata.client.ResumableUploader( client, f, 'video/mpeg', file_size, chunk_size=CHUNK_SIZE, desired_class=gdata.docs.data.DocsEntry) # Set metadata for our upload. entry = gdata.docs.data.DocsEntry(title=atom.data.Title(text='My Video')) new_entry = uploader.UploadFile('/feeds/upload/create-session/default/private/full', entry=entry) print 'Document uploaded: ' + new_entry.title.text print 'Quota used: %s' % new_entry.quota_bytes_used.text
สําหรับตัวอย่างที่สมบูรณ์และข้อมูลอ้างอิงซอร์สโค้ด โปรดดูแหล่งข้อมูลต่อไปนี้
- ตัวอย่างแอปและแหล่งที่มาไลบรารีของ Java
- ไลบรารี Objective-C ตัวอย่างแอป
- แหล่งที่มาของไลบรารี .NET