Bắt đầ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 các ứng dụng hoặc dịch vụ tự động hoá quy trình xác minh quyền sở hữu trang web hoặc miền. Đây là điều quan trọng vì một số Chỉ chủ sở hữu trang web hoặc miền mới có thể sử dụng các dịch vụ của Google. Bạn có thể sử dụng Google Site Verification API để xác thực rằng người dùng được xác thực là chủ sở hữu của miền hoặc trang web, có thể là người đầu tiên bước vào việc cung cấp các dịch vụ khác của Google theo phương thức lập trình.

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à bạn có thể sửa đổi các tệp hay bản ghi DNS của trang web hoặc miền của mình 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 những dịch vụ đó cho thấy rằng họ là chủ sở hữu của miền trang web cụ thể. Bạn có thể sử dụng API để tạo mã xác minh cho các mã Người dùng mà mã của bạn có thể đặt theo nhiều cách khác nhau trên trang web hoặc bản ghi tên miền trên thay mặt cho bạn. Khi mã thông báo đã sẵn sàng, bạn thực hiện lệnh gọi đến API để yêu cầu Google kiểm tra mã thông báo. Nếu tìm thấy mã này, Google sẽ đăng ký cho người dùng đã xác thực là 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 để xoá hoàn toàn quyền sở hữu trang web.

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

Hãy xem một 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 này, Google cần biết rằng thực sự sở hữu nó. Vì vậy, bạn 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 trang web. Họ cấp cho ứng dụng của bạn quyền truy cập vào dữ liệu xác minh của họ và ứng dụng có thể bây giờ, hãy thay mặt họ thực thi đoạn mã yêu cầu mã thông báo, đặt mã đó vào một tệp trên trang web của họ cấu trúc và yêu cầu Google kiểm tra cấu trúc đó. Khi tìm thấy mã thông báo, Google sẽ cấp quyền sở hữu trang web đến 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 để thông tin họ muốn.

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 để tự bảo vệ mình khỏi tình trạng mất dữ liệu ngoài ý muốn.

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

Nếu chưa hiểu rõ các khái niệm về API Google Site Verification, 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 quan trước khi bắt đầu lập trình.

Tìm hiểu cách uỷ quyền 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 đều phải bao gồm mã thông báo uỷ quyền. 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ẽ giúp bạn xử lý một số bước trong quá trình cấp phép.

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 gửi đến Google Site Verification API phải được 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ư mã ứng dụng khách và mật khẩu ứng dụng khách.
2. Kích hoạt Google Site Verification API 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 của OAuth 2.0 cho API xác minh trang web của Google:

Để 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ư mã ứng dụng khách và mật khẩu ứng dụng khách).

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 của Google Site

Khái niệm

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

• Miền: Miền hoặc miền con. Chủ sở hữu miền được coi là chủ sở hữu của tất cả các trang web và miền con thuộc 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: 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 xem là chủ sở hữu của tất cả các trang web thuộc miền đó. Ví dụ: chủ sở hữu của “http://www.example.com/site” cũng được xem là chủ sở hữu của “http://www.example.com/site/subsite”.

Vì quyền sở hữu miền có phạm vi áp dụng rộng hơn quyền sở hữu trang web, nên bạn cần xác minh thông qua miền bất cứ khi nào có thể.

Quy trình thiết lập quyền sở hữu bắt đầu bằng việc đăng ký yêu cầu một "mã xác minh" thay mặt cho 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 mã thông báo được thêm vào, ứng dụng của bạn có thể gửi yêu cầu đến Google Site Verification API để kiểm tra mã thông báo và ghi lại quyền sở hữu khi tìm thấy mã.

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

Vì lý do bảo mật và kỹ thuật, Google Site Verification API thực thi một số hạn chế về cách sử dụng API này:

• Chỉ truy cập dữ liệu cho người dùng đã xác thực: Tất cả các thao tác đều yêu cầu người dùng xác thực và uỷ quyền.
• Chỉ xác minh cho người dùng đã xác thực: API chỉ có thể xác minh quyền sở hữu trang web hoặc miền đối với tài khoản hiện đã được xác thực. Tuy nhiên, người dùng đã 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 đều được thông báo qua email bất cứ khi nào có thay đổi đối với danh sách quyền sở hữu.
• Chỉ URL và tên miền chuẩn hoá. API xác minh trang web của Google không hỗ trợ mã hoá IDN (Tên miền quốc tế). Hãy nhớ chuẩn hóa tất 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 §3.5) bằng cách sử dụng Mã hoá Puny nếu cần.

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

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 và đặ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 xem mã xác minh có tồn tại hay không: 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 nhằm xác minh rằng người dùng đã xác thực sở hữu trang web.

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

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

Hiện có hai phương thức xác minh cho miền:

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 công ty đăng ký tên miền của họ, bằng cách sử dụng mã thông báo cho dữ liệu bản ghi. Mã thông báo 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, phần thứ hai là giá trị của bản ghi CNAME mới.

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ọ, bằng cách sử dụng mã thông báo cho dữ liệu bản ghi.

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ó 3 phương thức xác minh cho các trang web:

Tệp

Ứng dụng của bạn sẽ đặ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 với nội dung 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 một tệp tại http://www.example.com/google12cfc68677988bb4.html (ở cấp cao nhất của trang web của họ), 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 sẽ chèn mã thông báo, dưới dạng thẻ HTML <meta>, trong phần tử <head> của tệp mặc định (index.html, default.html, v.v.) ở cấp cao nhất trên trang web của chủ sở hữu. Tệp HTML có mã 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.

Số liệu phân tích

Ứng dụng của bạn dùng mã theo dõi Google Analytics hiện có đã 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 và đoạn mã phải nằm trong thẻ HEAD thì mới có thể 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 của Analytics để biết thêm thông tin.

Trình quản lý thẻ

Ứng dụng của bạn 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 về phương pháp xác minh của Trình quản lý thẻ trong trung tâm trợ giúp để biết thêm thông tin.

Việc này có thể giúp bạn hiểu rõ các khái niệm và quy trình làm việc chính nếu trước hết 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 của quy trình Xác minh trang web.

Mô hình dữ liệu

Tài nguyên trê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.

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

{
  "owners": [
    "myself@example.com",
    "another@example.com"
  ],
  "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 riêng biệt của tài nguyên trên web này. Bạn có thể sử dụng công cụ này để tham chiếu tài nguyên web cụ thể này cho mục đích truy xuất và sửa đổi. Lưu trữ trường id từ kết quả của thao tác list (danh sách) để sau này sử dụng 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 bằng loại SITE; được chỉ định bằng kiểu INET_DOMAIN.

Mảng owners là danh sách đầy đủ các chủ sở hữu của tài nguyên trên web, được thể hiện bằng địa chỉ email của họ. Khi bạn thêm hoặc xoá địa chỉ email khỏi danh sách chủ sở hữu, người dùng đã xác thực có thể cấp quyền đồng sở hữu hoặc thu hồi quyền sở hữu đối với người dùng khác. Những chủ sở hữu khác đã đặt mã thông báo của riêng mình 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.

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

Thu thập tài nguyên web

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

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