Bắt đầu

Tài liệu này trình bày chi tiết kiến thức cơ bản mà bạn cần để sử dụng API xác minh trang web của Google.

1. Giới thiệu
2. Tổng quan
3. Trước khi bắt đầu
   1. Tạo Tài khoản Google
   2. Làm quen với API Xác minh trang web của Google
   3. Tìm hiểu cách cho phép yêu cầu
4. Nền tảng API xác minh trang web của Google
   1. Khái niệm
   2. Phương thức và mã thông báo xác minh
   3. Mô hình dữ liệu

Giới thiệu

API xác minh trang web của Google dành cho những nhà phát triển muốn viết ứng dụng hoặc dịch vụ tự động hóa quy trình xác minh quyền sở hữu đối với một trang web hoặc miền. Việc này rất quan trọng vì một số dịch vụ của Google chỉ dành cho chủ sở hữu trang web hoặc miền. Bạn có thể sử dụng API xác minh trang web của Google để xác thực rằng người dùng đã xác thực là chủ sở hữu của miền hoặc trang web, có thể là bước đầu tiên trong quá trình cấp phép cho các dịch vụ khác của Google.

Tài liệu này giả định rằng bạn đã quen thuộc với các khái niệm lập trình web, định dạng dữ liệu web và có thể chỉnh sửa tệp hoặc bản ghi DNS của trang web hoặc miền của bạn theo phương thức lập trình.

Tổng quan

Bạn có thể sử dụng API xác minh trang web của Google để sửa đổi dữ liệu xác minh trang web của người dùng trên Google. Người dùng chỉ có thể truy cập vào một số dịch vụ của Google nếu dữ liệu xác minh của họ cho thấy rằng họ là chủ sở hữu của một số miền trang web cụ thể. Bạn có thể sử dụng API để tạo mã xác minh cho người dùng đã xác thực. Mã của bạn có thể đặt theo nhiều cách trên trang web hoặc bản ghi miền của bạn. Sau khi thiết lập mã thông báo, bạn thực hiện lệnh gọi API để yêu cầu Google kiểm tra mã thông báo. Nếu tìm thấy mã thông báo, Google sẽ đăng ký người dùng đã xác thực làm chủ sở hữu của trang web hoặc miền. Bạn cũng có thể sử dụng API để sửa đổi danh sách quyền sở hữu thay mặt cho người dùng hoặc để xóa hoàn toàn quyền sở hữu trang web.

Tất cả lệnh gọi API đều cần được người dùng đã xác thực cấp phép và tất cả lệnh gọi API đều được thực thi trong bối cảnh của tài khoản người dùng đã xác thực.

Ví dụ cụ thể về thời điểm bạn có thể sử dụng API này, giả sử bạn cung cấp dịch vụ lưu trữ web. Người dùng của bạn muốn có thể sử dụng Search Console của Google để nhận thông tin về trang web của họ. Để làm được điều đó, Google cần biết rằng họ thực sự sở hữu URL đó. Như vậy, bạn sẽ cung cấp cho người dùng một giao diện yêu cầu họ xác minh quyền sở hữu đối với trang web. Ứng dụng của bạn sẽ cấp cho ứng dụng của bạn quyền truy cập vào dữ liệu xác minh và giờ đây, ứng dụng đó có thể thực thi mã yêu cầu mã thông báo, đặt mã đó vào một tệp trên cấu trúc trang web và yêu cầu Google kiểm tra mã đó. Khi tìm thấy mã thông báo, Google sẽ cấp quyền sở hữu trang web cho người dùng bằng cách cập nhật dữ liệu xác minh của họ. Giờ đây, họ có thể sử dụng Search Console để thu thập thông tin mong muốn.

Lưu ý: Thông tin về quyền sở hữu sẽ được lưu trữ và hiển thị cho các chủ sở hữu trang web khác (cả hiện tại và trong tương lai).

Trước khi bắt đầu

Tạo tài khoản Google

Bạn cần đảm bảo đã thiết lập Tài khoản Google. Bạn nên sử dụng một Tài khoản Google riêng cho mục đích phát triển và thử nghiệm để tránh việc vô tình bị mất dữ liệu.

Làm quen với quy trình Xác minh trang web

Nếu bạn chưa quen với các khái niệm về API xác minh trang web của Google, bạn nên đọc tài liệu này, thử nghiệm với giao diện người dùng xác minh và đọc tài liệu trợ giúp được liên kết trước khi bắt đầu lập trình.

Tìm hiểu cách cấp phép cho các yêu cầu

Mọi yêu cầu mà ứng dụng của bạn gửi tới API xác minh trang web của Google phải bao gồm mã cấp phép. Mã này cũng giúp Google xác định ứng dụng của bạn.

Giới thiệu về giao thức cấp phép

Ứng dụng của bạn phải sử dụng OAuth 2.0 để cấp phép các yêu cầu. Chúng tôi không hỗ trợ giao thức cấp phép nào khác. Nếu ứng dụng của bạn sử dụng chức năng Đăng nhập bằng Google, thì Google sẽ xử lý một số bước trong quá trình cấp phép cho bạn.

Cấp phép cho các yêu cầu bằng OAuth 2.0

Tất cả các yêu cầu đến API xác minh trang web của Google phải được một người dùng đã xác thực cấp phép.

Các chi tiết của quy trình cấp phép đối với OAuth 2.0 sẽ khác nhau đôi chút tuỳ thuộc vào loại ứng dụng bạn đang viết. Quy trình chung sau đây áp dụng cho tất cả các loại ứng dụng:

1. Khi tạo ứng dụng của mình, bạn sẽ đăng ký ứng dụng bằng Google API Console. Sau đó, Google cung cấp thông tin bạn sẽ cần sau này, chẳng hạn như ID ứng dụng khách và khoá bí mật của ứng dụng.
2. Kích hoạt API xác minh trang web của Google trong Google API Console. (Nếu API không được liệt kê trong API Console, thì hãy bỏ qua bước này.)
3. Khi cần quyền truy cập vào dữ liệu người dùng, ứng dụng sẽ yêu cầu Google cung cấp phạm vi truy cập cụ thể.
4. Google hiển thị màn hình yêu cầu sự đồng ý cho người dùng để hỏi xem họ có cho phép ứng dụng của bạn yêu cầu một số dữ liệu của họ hay không.
5. Nếu người dùng đồng ý, thì Google sẽ cấp cho ứng dụng của bạn một mã truy cập ngắn hạn.
6. Sau đó, ứng dụng yêu cầu dữ liệu người dùng và đính kèm mã truy cập trong yêu cầu.
7. Nếu xác định rằng yêu cầu của bạn và mã này là hợp lệ, Google sẽ trả về dữ liệu mà ứng dụng yêu cầu.

Một số quy trình cấp phép có các bước bổ sung khác, chẳng hạn như sử dụng mã làm mới để lấy mã truy cập mới. Để biết thông tin chi tiết về quy trình cho các loại ứng dụng khác nhau, hãy xem tài liệu về OAuth 2.0 của Google.

Dưới đây là thông tin về phạm vi truy cập của OAuth 2.0 cho API xác minh trang web của Google:

Phạm vi	Ý nghĩa
https://www.googleapis.com/auth/siteverification	Toàn quyền đọc đối với các trang web đã xác minh hiện có, khả năng xác minh các trang web mới.
https://www.googleapis.com/auth/siteverification.verify_only	Khả năng xác minh trang web mới, không có quyền đọc đối với các trang web đã xác minh hiện có.

Để yêu cầu quyền truy cập bằng OAuth 2.0, ứng dụng của bạn cần thông tin về mức truy cập, cũng như thông tin mà Google cung cấp khi bạn đăng ký ứng dụng của mình (chẳng hạn như ID ứng dụng khách và khoá bí mật của ứng dụng).

Mẹo: Thư viện ứng dụng API Google có thể xử lý một số bước trong quy trình cấp phép cho bạn. Thư viện này được cung cấp bằng nhiều ngôn ngữ lập trình. Hãy xem trang về các thư viện và mẫu để biết thêm chi tiết.

Nền API xác minh trang web của Google

Ý tưởng

Bạn có thể sử dụng API xác minh trang web của Google để xác lập quyền sở hữu của người dùng đối với các loại tài nguyên web sau đây:

• Miền: Miền hoặc miền con. Chủ sở hữu của một miền được coi là chủ sở hữu của tất cả các trang web và miền con của miền đó. Ví dụ: chủ sở hữu trực tiếp của bar.com cũng được coi là chủ sở hữu gián tiếp của foo.bar.com.
• Trang web: Một URL tương ứng với miền cơ sở và đường dẫn của một trang web. Chủ sở hữu của một trang web được coi là chủ sở hữu của tất cả các trang web trên trang web đó. Ví dụ: chủ sở hữu của “http://www.example.com/site” cũng được coi là chủ sở hữu của “http://www.example.com/site/subsite”.

Do quyền sở hữu miền áp dụng rộng hơn so với quyền sở hữu trang web, bạn nên xác minh với các miền bất cứ khi nào có thể.

Quá trình thiết lập quyền sở hữu bắt đầu từ việc ứng dụng của bạn yêu cầu “mã xác minh” thay mặt người dùng. Mã xác minh là một chuỗi đặc biệt mà mã của bạn phải đặt trên trang web hoặc miền của họ. Sau khi có mã thông báo, ứng dụng của bạn có thể gửi yêu cầu tới API Xác minh trang web của Google. API này sẽ kiểm tra mã thông báo và ghi lại quyền sở hữu khi tìm thấy mã thông báo.

Các điểm hạn chế

Vì lý do bảo mật và kỹ thuật, API xác minh trang web của Google thực thi một số hạn chế về cách sử dụng API đó:

• Chỉ truy cập dữ liệu cho người dùng được xác thực: Tất cả các hoạt động đều yêu cầu người dùng phải xác thực và ủy quyền.
• Chỉ xác minh người dùng đã xác thực: API chỉ có thể xác minh quyền sở hữu đối với các trang web hoặc miền cho tài khoản hiện đã xác thực. Tuy nhiên, người dùng được xác thực có thể uỷ quyền sở hữu cho người dùng khác sau khi quyền sở hữu của họ đối với một trang web đã được xác minh. Xin lưu ý rằng tất cả chủ sở hữu sẽ nhận được thông báo qua email bất cứ khi nào có thay đổi về danh sách quyền sở hữu.
• Chỉ các URL và tên miền được chuẩn hoá. API xác minh trang web của Google không hỗ trợ mã hóa IDN (Tên miền quốc tế). Hãy đảm bảo chuẩn hóa tất cả các URL, tên miền và miền địa chỉ email thành bộ ký tự tên miền chuẩn (RFC 1034 – Điều §3.5) bằng cách sử dụng công cụ mã hóa nếu cần.

Phương thức xác minh và mã thông báo

API này cung cấp lệnh gọi cho các giai đoạn xác minh riêng biệt:

• Đặt mã xác minh: Có một lệnh gọi API để truy xuất mã xác minh để đặt trên trang web của người dùng đã xác thực. Nếu người dùng có nhiều trang web, bạn phải lấy mã thông báo khác nhau cho mỗi trang web.
• Kiểm tra sự hiện diện của mã thông báo xác minh: Có một lệnh gọi API riêng biệt yêu cầu Google kiểm tra mã thông báo để xác minh rằng người dùng đã xác thực sở hữu một trang web.

Có một số phương pháp để xác minh trang web hoặc miền mà ứng dụng của bạn có thể sử dụng. Phương thức bạn chọn phụ thuộc vào phương thức phù hợp nhất với yêu cầu của bạn. Nơi đặt mã thông báo, cũng như loại mã thông báo, tùy thuộc vào phương thức xác minh mà bạn chọn.

Phương thức xác minh miền

Miền có hai phương thức xác minh:

DNS_CNAME

Ứng dụng của bạn tạo một bản ghi CNAME mới cho miền của chủ sở hữu, có thể thông qua nhà đăng ký tên miền của họ, sử dụng mã thông báo cho dữ liệu đó. Mã thông báo bao gồm hai phần được phân tách bằng dấu cách: phần đầu tiên là tên của bản ghi CNAME mới, giá trị thứ hai là giá trị mới của bản ghi CNAME.

DNS_TXT

Ứng dụng của bạn tạo một bản ghi TXT mới cho miền của chủ sở hữu, có thể thông qua nhà đăng ký tên miền của họ, sử dụng mã thông báo cho dữ liệu đó.

Hãy xem tài liệu trong trung tâm trợ giúp về phương thức xác minh DNS để biết thêm thông tin.

Phương thức xác minh trang web

Có ba phương pháp xác minh cho các trang web:

Tệp

Ứng dụng của bạn đặt mã thông báo dưới dạng tệp trên trang web của chủ sở hữu. Bạn phải tạo một tệp có tên khớp với chuỗi mã thông báo như sau:

google-site-verification: token

Ví dụ: nếu người dùng sở hữu trang web http://www.example.com/ và mã thông báo được trả về là google12cfc68677988bb4.html, thì bạn chỉ cần tạo tệp tại http://www.example.com/google12cfc68677988bb4.html (ở cấp cao nhất của trang web) với những nội dung sau:

google-site-verification: google12cfc8677988bb4.html

Hãy xem tài liệu trong trung tâm trợ giúp về Phương thức xác minh tệp để biết thêm thông tin.

Meta

Ứng dụng của bạn chèn mã thông báo, dưới dạng thẻ <meta> HTML, trong phần tử <head> của tệp mặc định (index.html, default.html, v.v.) ở cấp cao nhất của trang web của chủ sở hữu. Tệp HTML có mã thông báo xác minh Meta có thể có dạng như sau:

<html>
  <head>
    <title>Awesome Dive Sites</title>
    <meta name="google-site-verification" content="-dhsoFQadgDKJR7BsB6bc1j5yfqjUpg_b-1pFjr7o3x" />
  </head>
  <body>
    ...

Hãy xem tài liệu trong trung tâm trợ giúp về Phương thức xác minh meta để biết thêm thông tin.

Phân tích

Ứng dụng của bạn sử dụng mã theo dõi hiện có của Google Analytics đã có trên trang web của chủ sở hữu. Mã theo dõi phải thuộc về tài khoản Analytics của họ và đoạn mã phải nằm trong thẻ HEAD để hoạt động. Hãy xem tài liệu trong trung tâm trợ giúp về Phương thức xác minh Analytics để biết thêm thông tin.

Trình quản lý thẻ

Ứng dụng của bạn sử dụng mã vùng chứa Trình quản lý thẻ của Google hiện có đã có trên trang web của chủ sở hữu. Mã vùng chứa phải thuộc về tài khoản Trình quản lý thẻ của họ. Hãy xem tài liệu trong trung tâm trợ giúp về Phương thức xác minh Trình quản lý thẻ để biết thêm thông tin.

Điều này có thể giúp bạn hiểu các khái niệm và quy trình làm việc chính nếu trước tiên bạn thử xác minh một vài trang web theo cách thủ công bằng giao diện người dùng Xác minh trang web.

Mô hình dữ liệu

Tài nguyên web

API xác minh trang web của Google áp dụng ngữ nghĩa REST (HTTP GET, POST, v.v.) cho các thực thể được gọi là tài nguyên web. Tài nguyên web là một trang web hoặc miền thuộc về người dùng đã xác thực.

Sau đây là ví dụ về một tài nguyên trên web:

{
  "owners": [
    "[e-mail]",
    "[e-mail]"
  ],
  "id": "http%3A%2F%2Fwww.example.com%2F",
  "site": {
    "identifier": "http://www.example.com/",
    "type": "SITE"
  }
}

Trường id là giá trị nhận dạng duy nhất cho tài nguyên web này. Bạn sử dụng tham chiếu này để tham chiếu tài nguyên web cụ thể này để truy xuất và sửa đổi. Lưu trữ trường id từ kết quả của hoạt động list để dùng sau này làm giá trị nhận dạng.

Đối tượng site chứa URL hoặc tên miền của tài nguyên web và loại tài nguyên. Các trang web được chỉ định thuộc loại SITE; các miền được chỉ định với loại INET_DOMAIN.

Mảng owners là danh sách đầy đủ các chủ sở hữu của tài nguyên web, được biểu thị bằng địa chỉ email của họ. Bằng cách thêm hoặc xoá địa chỉ email khỏi danh sách chủ sở hữu, người dùng được xác thực có thể cấp quyền sở hữu hoặc thu hồi quyền sở hữu cho người dùng khác. Những chủ sở hữu khác đã đặt mã của riêng họ trên trang web hoặc miền đó cũng sẽ xuất hiện trong danh sách chủ sở hữu, cùng với bất kỳ người đồng sở hữu nào.

Người dùng đã được cấp quyền đồng sở hữu cũng có thể cấp quyền sở hữu, miễn là có ít nhất một chủ sở hữu được xác minh bằng mã thông báo trên trang web.

Thu thập tài nguyên web

Bộ sưu tập tài nguyên web là một danh sách đầy đủ tất cả tài nguyên web thuộc về người dùng đã được xác thực. Bạn có thể xác minh quyền sở hữu đối với các trang web hoặc miền bằng cách cố gắng thêm tài nguyên web mới vào bộ sưu tập tài nguyên web của người dùng đã được xác thực. Chỉ những trang web hoặc miền đã xác minh mới được thêm thành công vào bộ sưu tập của họ.

Như đã nêu trong phần Giới hạn, bạn không thể truy cập các tài nguyên web thuộc về người dùng không phải người dùng đã xác thực thông qua API xác minh trang web.