Kiến thức cơ bản về giao thức API dữ liệu của Google

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

Để biết thêm thông tin về API Dữ liệu của Google, hãy xem tài liệu Hướng dẫn dành cho nhà phát triển dữ liệu của Google và Hướng dẫn tham khảo.

Đố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.

Ví dụ

Những ví dụ sau đây minh họa các yêu cầu giao thức API dữ liệu bạn có thể gửi đến một dịch vụ chung 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 API Dữ liệu của 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 từng 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 sau đến máy chủ:

GET /myFeed

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

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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ả.

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"?>
<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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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 với tất cả cá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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

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

Để cập nhật một mục nhập hiện có, hãy sử dụng PUT với URI chỉnh sửa của mục nhập (như được máy chủ cung cấp trong ví dụ trước, trong phần tử <link rel="edit">).

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

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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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 URI chỉnh sửa đã thay đổi; giờ đây, URI này kết thúc bằng "/2/" thay vì "/1/". Số cuối cùng trong URI chỉnh sửa là số phiên bản. Để biết thêm thông tin về các phiên bản, hãy xem phần Tính năng đồng thời tối ưu trong 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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

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

Ví dụ sau đây xoá một mục:

DELETE /myFeed/1/2/

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:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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.

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