Kiến thức cơ bản về giao thức

Cảnh báo: Trang này giới thiệu về các API cũ của Google, API dữ liệu của Google; trang này chỉ liên quan đến các API được liệt kê trong thư mục API dữ liệu của Google, nhiều API trong số này đã được thay thế bằng các API mới hơn. Để biết thông tin về một API mới cụ thể, hãy xem tài liệu của API mới. Để biết thông tin về việc uỷ quyền cho các yêu cầu bằng một API mới hơn, hãy xem phần Xác thực và ủy quyền tài khoản Google.

Tài liệu này mô tả các khái niệm cơ bản của Giao thức dữ liệu của Google được nhiều Google API sử dụng, bao gồm các ví dụ về truy vấn trông như thế nào, kết quả trông như thế nào, v.v.

Để biết thêm thông tin về Giao thức dữ liệu Google, hãy xem trang tổng quan Hướng dẫn dành cho nhà phát triển và Tài liệu tham khảo về giao thức.

Đối tượng người xem

Tài liệu này dành cho những ai muốn tìm hiểu ý tưởng chung về định dạng XML và giao thức mà API Dữ liệu của Google sử dụng.

Ngay cả khi chỉ muốn viết mã sử dụng thư viện ứng dụng dành riêng cho ngôn ngữ, bạn vẫn có thể đọc tài liệu này để hiểu được điều gì đang diễn ra bên dưới lớp trừu tượng trong thư viện ứng dụng.

Tài liệu này giả định rằng bạn hiểu được các khái niệm cơ bản về XML, vùng chứa tên, nguồn cấp dữ liệu được phân phối và các yêu cầu GET, POST, PUT và DELETE trong HTTP, cũng như khái niệm "tài nguyên" của HTTP. Để biết thêm thông tin về những vấn đề đó, hãy xem phần Tài nguyên bổ sung của tài liệu này.

Tài liệu này không dựa vào bất kỳ ngôn ngữ lập trình cụ thể nào; máy khách của bạn có thể tương tác với máy chủ bằng cách sử dụng bất kỳ ngôn ngữ lập trình nào cho phép bạn đưa ra yêu cầu HTTP và phân tích cú pháp phản hồi dựa trên XML.

Nếu muốn thử các ví dụ trong tài liệu này mà không cần viết mã, bạn có thể thấy URL tiện ích dòng lệnh cW hoặc Wget hữu ích; để biết thêm thông tin, hãy xem trang thủ công cho các tiện ích đó hoặc tài liệu về Sử dụng cURL để tương tác với các dịch vụ sử dụng Giao thức dữ liệu Google.

Ví dụ

Những ví dụ sau đây minh họa các yêu cầu HTTP mà bạn có thể gửi đến một dịch vụ chung bằng cách sử dụng giao thức API Dữ liệu giao thức Google trực tiếp và kết quả bạn có thể nhận được. Để biết ví dụ về cách gửi yêu cầu bằng nhiều ngôn ngữ lập trình, hãy xem mẫu và thư viện ứng dụng theo ngôn ngữ. Để biết thông tin về cách sử dụng Giao thức dữ liệu Google với các dịch vụ cụ thể của Google, hãy xem tài liệu dành riêng cho dịch vụ.

Yêu cầu nguồn cấp dữ liệu hoặc tài nguyên khác

Giả sử có một nguồn cấp dữ liệu tên là /myFeed và giả định rằng nguồn cấp dữ liệu đó hiện không chứa bất kỳ mục nhập nào. Để xem yêu cầu, hãy gửi yêu cầu HTTP sau đây đến máy chủ:

GET /myFeed

Máy chủ phản hồi:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Lưu ý rằng mặc dù nguồn cấp dữ liệu không chứa bất kỳ mục nhập nào, nhưng nguồn cấp dữ liệu lại chứa siêu dữ liệu, chẳng hạn như tiêu đề và tên tác giả. Tệp này cũng chứa giá trị nhận dạng phiên bản, dưới dạng HTTP ETag.

Chèn mục nhập mới

Để tạo một mục nhập mới, hãy gửi yêu cầu POST và cung cấp bản trình bày XML của mục nhập mới:

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Xin lưu ý rằng bạn không cung cấp các phần tử tiêu chuẩn <id>, <link> hoặc <updated> tiêu chuẩn; máy chủ sẽ tạo các phần tử đó để đáp ứng yêu cầu POST của bạn. Ngoài ra, xin lưu ý rằng tác giả của nguồn cấp dữ liệu không nhất thiết phải là người giống như tác giả của một mục nhập.

Máy chủ phản hồi:

201 CREATED

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Tìm kiếm chuỗi

Để tìm kiếm toàn bộ văn bản cho một chuỗi cụ thể, khi sử dụng một dịch vụ có hỗ trợ tìm kiếm toàn bộ văn bản, hãy gửi yêu cầu GET có tham số q. Để biết thêm thông tin về các tham số truy vấn, hãy xem phần Yêu cầu truy vấn trong tài liệu tham khảo về giao thức.

GET /myFeed?q=This

Máy chủ phản hồi bằng một nguồn cấp dữ liệu chứa tất cả mục nhập khớp với chuỗi tìm kiếm This. (Trong trường hợp này, chỉ có một phương pháp.)

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

Cập nhật mục nhập

Để cập nhật mục nhập hiện có, bạn cần thực hiện các bước sau.

  1. Truy xuất mục nhập bạn muốn cập nhật.
  2. Hãy chỉnh sửa theo ý muốn.
  3. Gửi yêu cầu PUT, với mục nhập đã cập nhật trong nội dung thông báo, đến URI chỉnh sửa của mục nhập. URI chỉnh sửa xuất hiện trong ví dụ trước dưới dạng thuộc tính href của phần tử <link rel='edit'>.

Bạn cũng phải chỉ định ETag của mục nhập ban đầu, để đảm bảo rằng bạn không ghi đè các thay đổi của bất kỳ ai khác.

Trong ví dụ sau, chúng tôi sẽ thay đổi văn bản của mục nhập từ giá trị cũ ("Đây là mục nhập của tôi") thành giá trị mới ("Đây là mục đầu tiên của tôi".):

PUT /myFeed/1/1/

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Máy chủ phản hồi:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Lưu ý rằng ETag đã thay đổi. Để biết thêm thông tin về các phiên bản tài nguyên, hãy xem phần Tạo phiên bản tài nguyên (ETag) của tài liệu tham khảo về giao thức.

Để xem mục nhập mới trong ngữ cảnh, hãy yêu cầu lại toàn bộ tài nguyên:

GET /myFeed

Máy chủ phản hồi:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

Lưu ý: Nếu tường lửa của bạn không cho phép PUT, hãy thực hiện HTTP POST và đặt tiêu đề ghi đè phương thức như sau:

X-HTTP-Method-Override: PUT

Xoá mục nhập

Để xoá một mục nhập hiện có, hãy gửi yêu cầu DELETE, sử dụng URI chỉnh sửa của mục nhập đó (như được máy chủ cung cấp trong ví dụ trước).

Nếu tường lửa của bạn không cho phép DELETE, hãy thực hiện HTTP POST và đặt tiêu đề ghi đè phương thức như sau:

X-HTTP-Method-Override: DELETE

Khi xoá một mục nhập, bạn có thể chọn xoá mục có điều kiện (chỉ xoá nếu mục đó không thay đổi kể từ lần truy xuất gần đây nhất) hoặc một mục xoá không có điều kiện. Để biết thêm thông tin, hãy xem phần Tạo phiên bản tài nguyên (ETag) của tài liệu tham khảo về giao thức. Để xoá không có điều kiện, hãy đặt tiêu đề HTTP sau đây:

If-Match: *

Ví dụ sau đây sẽ xoá một mục nhập (nếu bạn đặt tiêu đề phù hợp):

DELETE /myFeed/1/

Máy chủ phản hồi:

200 OK

Thực hiện một thao tác GET khác để xem nguồn cấp dữ liệu hiện không chứa mục nào:

GET /myFeed

Máy chủ phản hồi bằng một nguồn cấp dữ liệu không chứa gì ngoài siêu dữ liệu:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Nếu thao tác xoá không thành công thì máy chủ sẽ phản hồi bằng mã lỗi. Để biết thêm thông tin, hãy xem Mã trạng thái HTTP trong tài liệu tham khảo về giao thức.

Yêu cầu nguồn cấp dữ liệu hoặc mục nhập một phần (Thử nghiệm)

Khác với nguồn cấp dữ liệu mẫu đơn giản trong tài liệu này, trên thực tế, nguồn cấp dữ liệu có thể khá phức tạp. Với một số API, bạn chỉ có thể yêu cầu các phần tử hoặc thuộc tính quan tâm, thay vì biểu diễn toàn bộ tài nguyên. Khi tránh truy xuất và phân tích cú pháp dữ liệu không cần thiết, bạn có thể cải thiện đáng kể hiệu quả của ứng dụng của mình.

Để yêu cầu phản hồi một phần, hãy sử dụng tham số truy vấn fields để chỉ định các phần tử hoặc thuộc tính mà bạn muốn trả về. Để biết thêm thông tin, hãy xem phần Phản hồi một phần trong tài liệu tham khảo về giao thức.

Ví dụ sau đây chỉ yêu cầu mã nguồn cấp dữ liệu, tác giả và tiêu đề cho mỗi mục nhập nguồn cấp dữ liệu,

GET /myFeed?fields=id,entry(author)

Máy chủ phản hồi:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

Bạn có thể dùng tham số fields với bất kỳ loại yêu cầu nào trả về dữ liệu. Ngoài GET, các kênh này bao gồm POST và PUT (cũng như PATCH, được dùng để yêu cầu cập nhật một phần).

Lưu ý: Tham số truy vấn fields chỉ kiểm soát dữ liệu được gửi lại theo yêu cầu; không ảnh hưởng đến dữ liệu mà bạn phải cung cấp trong phần nội dung của yêu cầu PUT, POST hoặc PATCH.

Dưới đây là ví dụ về POST và PUT.

  • Khi đưa ra yêu cầu POST cho phản hồi một phần, bạn vẫn phải cung cấp cùng một dữ liệu như mô tả trong phần Chèn mục nhập mới. Ví dụ sau đây yêu cầu phản hồi một phần chỉ chứa tiêu đề của mục mới tạo: 
    POST /myFeed?fields=title
      
...data...

    Máy chủ phản hồi:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • Khi đưa ra yêu cầu PUT cho phản hồi một phần, bạn vẫn phải cung cấp phiên bản chỉnh sửa của bản trình bày tài nguyên đầy đủ, như mô tả trong phần Cập nhật mục nhập. Ví dụ sau đây yêu cầu một phản hồi một phần chỉ chứa giá trị ETag mới của mục nhập được sửa đổi: 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...

    Máy chủ phản hồi:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

Cập nhật các trường cụ thể (Thử nghiệm)

Nếu API bạn đang sử dụng hỗ trợ phản hồi một phần và có các trường có thể chỉnh sửa, bạn cũng có thể tránh gửi dữ liệu không cần thiết khi sửa đổi mục nhập. Tính năng Cập nhật một phần chỉ cho phép bạn gửi dữ liệu cho những trường mà bạn muốn thay đổi.

Để sử dụng tính năng cập nhật một phần, bạn gửi yêu cầu PATCH đến cùng một URI chỉnh sửa mà bạn sử dụng với PUT. Dữ liệu mà bạn gửi bằng PATCH phải tuân thủ một số quy ước nhất định. Tuy nhiên, ngữ nghĩa đủ linh hoạt để bạn thay thế dữ liệu trong tài nguyên mục tiêu, thêm vào hoặc thậm chí là xóa dữ liệu khỏi tài nguyên đích, tất cả chỉ bằng một yêu cầu duy nhất.

Lưu ý: Tương tự như PUT, bạn phải chỉ định ETag của mục nhập ban đầu để đảm bảo bạn không ghi đè thay đổi của người khác.

Để biết thêm thông tin về PATCH và ngữ nghĩa của lớp này, xem Cập nhật một phần trong tài liệu tham khảo về giao thức.

Ví dụ này hiển thị một yêu cầu cập nhật một phần để sửa đổi tiêu đề của mục nhập:

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag="EksPTg1Bfyp7IWA6WhJT"
    gd:fields='title'>
  <title>New Title</title>
</entry>

Khi nhận được một yêu cầu PATCH, máy chủ sẽ xoá mọi trường do thuộc tính gd:fields của mục nhập (nếu có); sau đó hợp nhất mọi dữ liệu được cung cấp trong nội dung yêu cầu với tài nguyên đích. Trong ví dụ này, thành phần tiêu đề trước tiên sẽ bị xoá khỏi tài nguyên đích; sau đó giá trị tiêu đề mới sẽ được hợp nhất. Yêu cầu này hiệu quả thay thế tiêu đề cũ bằng tiêu đề mới.

Tuy nhiên, hãy lưu ý rằng ngữ nghĩa của PATCH sẽ hợp nhất biểu thị một phần vào tài nguyên hiện có. Không phải lúc nào bạn cũng phải xóa một trường để cập nhật giá trị của trường đó.

  • Nếu trường chỉ có thể tồn tại một lần trong mục nhập mục tiêu, thì khi hợp nhất, trường đó trong trường đại diện một phần sẽ ghi đè trường tương ứng trong mục tiêu mục tiêu.
  • Nếu trường này có thể tồn tại nhiều lần trong mục nhập mục tiêu, thì khi hợp nhất, trường này sẽ được thêm vào mục nhập một phần.

Ví dụ tiếp theo cho thấy sự khác biệt giữa cách các trường lặp lại và các trường không lặp lại. Điều này sẽ bổ sung thêm tiêu đề và tác giả mới vào mục nhập mà không cần sử dụng thuộc tính gd:fields để xóa một trong hai trường đó trước.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

Vì phần biểu thị mục nhập một phần không có thuộc tính gd:fields nên không có trường nào bị xoá. Tuy nhiên, các giá trị mới cho các phần tử <title> và <author> được hợp nhất với tài nguyên mục tiêu:

  • Vì Atom chỉ cho phép một tiêu đề cho mỗi mục nhập, nên tiêu đề mới sẽ ghi đè giá trị hiện có. 
  • Vì Atom cho phép nhiều tác giả trên mỗi mục nhập, nên tác giả mới sẽ được thêm vào danh sách thành phần tác giả đã có trong tài nguyên đích.

    Lưu ý: Không phải tất cả các API đều tuân theo tiêu chuẩn Atom. Ví dụ: một số API chỉ cho phép một phần tử <author> cho mỗi mục nhập; những API khác kế thừa tác giả của mục nhập từ cấp nguồn cấp, làm cho trường chỉ có thể đọc.

Sau khi xử lý một yêu cầu PATCH hợp lệ, máy chủ sẽ trả về mã trạng thái HTTP 200, cùng với bản sao đại diện đầy đủ của mục nhập đã cập nhật.

Nếu muốn máy chủ chỉ trả về một số phần tử hoặc thuộc tính nhất định, thì bạn có thể sử dụng tham số truy vấn fields với PATCH để yêu cầu phản hồi một phần.

Tài nguyên khác

Bạn có thể thấy các tài liệu bên thứ ba sau đây hữu ích:

Trở lại đầu trang