Trang này được dịch bởi Cloud Translation API.

Search Analytics: query

Truy vấn dữ liệu lưu lượng truy cập tìm kiếm bằng bộ lọc và thông số mà bạn xác định. Phương thức này trả về 0 hoặc nhiều hàng được nhóm theo các khoá hàng (phương diện) mà bạn xác định. Bạn phải xác định phạm vi ngày gồm một hoặc nhiều ngày.

Khi ngày là một trong các phương diện, thì bất kỳ ngày nào không có dữ liệu sẽ bị loại khỏi danh sách kết quả. Để tìm hiểu ngày nào có dữ liệu, hãy đưa ra truy vấn mà không dùng bộ lọc được nhóm theo ngày, cho phạm vi ngày mà bạn quan tâm.

Kết quả được sắp xếp theo số lượt nhấp giảm dần. Nếu 2 hàng có cùng số lượt nhấp, chúng sẽ được sắp xếp theo cách tuỳ ý.

Hãy xem mẫu python để gọi phương thức này.

API này bị hạn chế bởi các giới hạn nội bộ của Search Console và không đảm bảo sẽ trả về tất cả các hàng dữ liệu, ngoại trừ các hàng hàng đầu.

Xem giới hạn về lượng dữ liệu có sẵn.

Ví dụ về POST cho JSON:

POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
  "startDate": "2015-04-01",
  "endDate": "2015-05-01",
  "dimensions": ["country","device"]
}

Thử ngay.

Yêu cầu

Yêu cầu HTTP

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

Tham số

Tên thông số	Giá trị	Nội dung mô tả
Tham số đường dẫn
`siteUrl`	`string`	URL của tài sản như được xác định trong Search Console. Ví dụ: `http://www.example.com/` (đối với tài sản có tiền tố URL) hoặc `sc-domain:example.com` (đối với Tài sản miền)

Ủy quyền

Yêu cầu này cần có sự uỷ quyền với ít nhất một trong các phạm vi sau (đọc thêm về tính năng xác thực và uỷ quyền).

Phạm vi
`https://www.googleapis.com/auth/webmasters.readonly`
`https://www.googleapis.com/auth/webmasters`

Nội dung yêu cầu

Trong nội dung yêu cầu, hãy cung cấp dữ liệu theo cấu trúc sau:

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}

Tên tài sản	Giá trị	Nội dung mô tả
`startDate`	`string`	[Bắt buộc] Ngày bắt đầu của phạm vi ngày được yêu cầu, ở định dạng YYYY-MM-DD, theo giờ Thái Bình Dương (UTC – 7:00/8:00). Phải nhỏ hơn hoặc bằng ngày kết thúc. Giá trị này có trong phạm vi.
`endDate`	`string`	[Bắt buộc] Ngày kết thúc của phạm vi ngày được yêu cầu, ở định dạng YYYY-MM-DD, theo giờ Thái Bình Dương (UTC – 7:00/8:00). Phải lớn hơn hoặc bằng ngày bắt đầu. Giá trị này có trong phạm vi.
`dimensions[]`	`list`	[Không bắt buộc] Không có hoặc có nhiều phương diện để nhóm kết quả theo.Kết quả được nhóm theo thứ tự mà bạn cung cấp các phương diện này.Bạn có thể sử dụng bất kỳ tên phương diện nào trong `dimensionFilterGroups[].filters[].dimension` hoặc "ngày".Các giá trị phương diện nhóm được kết hợp để tạo ra một khoá duy nhất cho mỗi hàng kết quả. Nếu bạn không chỉ định phương diện, tất cả các giá trị sẽ được kết hợp thành một hàng duy nhất. Không có giới hạn về số lượng phương diện mà bạn có thể nhóm theo, nhưng bạn không thể nhóm theo cùng một phương diện hai lần. Ví dụ: [country, device]
`searchType`	`string`	Không dùng nữa, chuyển sang dùng `type`
`type`	`string`	[Không bắt buộc] Lọc kết quả theo loại sau: "`discover`": Khám phá các kết quả "`googleNews`": Kết quả từ news.google.com và ứng dụng Google News trên Android và iOS. Không bao gồm kết quả từ thẻ "Tin tức" trong Google Tìm kiếm. "`news`": Kết quả tìm kiếm trên thẻ "Tin tức" trong Google Tìm kiếm. "`image`": Kết quả tìm kiếm qua thẻ "Hình ảnh" trong Google Tìm kiếm. "`video`": Kết quả tìm kiếm video "`web`": [Mặc định] Lọc kết quả theo thẻ tổng hợp ("Tất cả") trong Google Tìm kiếm. Không bao gồm kết quả trên Khám phá hoặc Google News.
`dimensionFilterGroups[]`	`list`	[Không bắt buộc] Không có hoặc có nhiều nhóm bộ lọc để áp dụng cho các giá trị nhóm phương diện. Tất cả các nhóm bộ lọc phải khớp thì mới được trả về một hàng trong phản hồi. Trong một nhóm bộ lọc, bạn có thể chỉ định xem tất cả bộ lọc phải khớp hay có ít nhất một bộ lọc phù hợp.
`dimensionFilterGroups[].groupType`	`string`	Liệu tất cả bộ lọc trong nhóm này có trả về giá trị true ("và") hay không, hay một hoặc nhiều bộ lọc phải trả về giá trị true (chưa được hỗ trợ). Các giá trị được chấp nhận là: "`and`": Tất cả các bộ lọc trong nhóm phải trả về giá trị true (đúng) cho nhóm bộ lọco.
`dimensionFilterGroups[].filters[]`	`list`	[Không bắt buộc] Không có hoặc có nhiều bộ lọc để kiểm tra hàng. Mỗi bộ lọc bao gồm một tên phương diện, một toán tử và một giá trị. Độ dài tối đa 4096 ký tự. Ví dụ: country equals FRA query contains mobile use device notContains tablet
`dimensionFilterGroups[].filters[].dimension`	`string`	Phương diện mà bộ lọc này áp dụng. Bạn có thể lọc theo bất kỳ phương diện nào được liệt kê ở đây, ngay cả khi bạn không nhóm theo phương diện đó. Các giá trị được chấp nhận là: "`country`": Lọc theo quốc gia đã chỉ định theo mã quốc gia gồm 3 chữ cái (ISO 3166-1 alpha-3). "`device`": Lọc kết quả theo loại thiết bị được chỉ định. Các giá trị được hỗ trợ: Máy tính để bàn THIẾT BỊ DI ĐỘNG Máy tính bảng "`page`": Lọc theo chuỗi URI được chỉ định. "`query`": Lọc theo chuỗi truy vấn được chỉ định. "`searchAppearance`": Lọc theo một tính năng trong kết quả tìm kiếm cụ thể. Để xem danh sách giá trị hiện có, hãy chạy truy vấn được nhóm theo "searchAppearance".
`dimensionFilterGroups[].filters[].operator`	`string`	[Không bắt buộc] Cách giá trị bạn chỉ định phải khớp (hoặc không khớp) với giá trị phương diện cho hàng. Các giá trị được chấp nhận là: "`contains`": Giá trị hàng phải chứa hoặc bằng biểu thức của bạn (không phân biệt chữ hoa chữ thường). "`equals`": [Mặc định] Biểu thức của bạn phải bằng chính xác giá trị hàng (phân biệt chữ hoa chữ thường đối với thứ nguyên trang và thứ nguyên truy vấn). "`notContains`": Giá trị hàng không được chứa biểu thức của bạn dưới dạng chuỗi con hoặc kết quả khớp hoàn toàn (không phân biệt chữ hoa chữ thường). "`notEquals`": Biểu thức của bạn không được chính xác bằng giá trị hàng (phân biệt chữ hoa chữ thường đối với thứ nguyên trang và thứ nguyên truy vấn). "`includingRegex`": Biểu thức chính quy cú pháp RE2 phải khớp. "`excludingRegex`": Biểu thức chính quy cú pháp RE2 không được so khớp.
`dimensionFilterGroups[].filters[].expression`	`string`	Giá trị để bộ lọc so khớp hoặc loại trừ, tuỳ thuộc vào toán tử.
`aggregationType`	`string`	[Không bắt buộc] Cách tổng hợp dữ liệu. Nếu tổng hợp theo tài sản thì tất cả dữ liệu cho cùng một tài sản sẽ được tổng hợp. Nếu được tổng hợp theo trang, tất cả dữ liệu sẽ được tổng hợp theo URI chính tắc. Nếu bạn lọc hoặc nhóm theo trang, hãy chọn tự động. Nếu không, bạn có thể tổng hợp theo tài sản hoặc theo trang, tuỳ thuộc vào cách bạn muốn tính toán dữ liệu. Hãy xem tài liệu trợ giúp để tìm hiểu cách tính dữ liệu theo trang web và theo trang. Lưu ý: Nếu nhóm hoặc lọc theo trang, thì bạn không thể tổng hợp theo tài sản. Nếu bạn chỉ định bất kỳ giá trị nào khác ngoài giá trị tự động, thì loại tổng hợp trong kết quả sẽ khớp với loại được yêu cầu hoặc nếu bạn yêu cầu một loại không hợp lệ, bạn sẽ nhận được thông báo lỗi. API sẽ không bao giờ thay đổi loại tổng hợp của bạn nếu loại được yêu cầu không hợp lệ. Các giá trị được chấp nhận là: "`auto`": [Mặc định] Để dịch vụ quyết định loại tổng hợp phù hợp. "`byNewsShowcasePanel`": Tổng hợp các giá trị theo bảng điều khiển tính năng Nổi bật trên Google News. Bạn phải sử dụng giá trị này kết hợp với bộ lọc `NEWS_SHOWCASE` `searchAppearance` và `type=discover` hoặc `type=googleNews`. Nếu bạn nhóm theo trang, lọc theo trang hoặc lọc theo một `searchAppearance` khác, thì bạn sẽ không thể tổng hợp theo `byNewsShowcasePanel`. "`byPage`": Tổng hợp các giá trị theo URI. "`byProperty`": Tổng hợp các giá trị theo tài sản. Không được hỗ trợ cho `type=discover` hoặc `type=googleNews`
`rowLimit`	`integer`	[Không bắt buộc; Phạm vi hợp lệ là 1 đến 25.000; Mặc định là 1.000] Số hàng tối đa cần trả về. Để phân trang kết quả, hãy sử dụng độ lệch `startRow`.
`startRow`	`integer`	[Không bắt buộc; Mặc định là 0] Chỉ mục gốc của hàng đầu tiên trong phản hồi. Phải là một số không âm. Nếu `startRow` vượt quá số lượng kết quả cho truy vấn, thì phản hồi sẽ là phản hồi thành công không có hàng.
`dataState`	`string`	[Không bắt buộc] Nếu là "all" (không phân biệt chữ hoa chữ thường), dữ liệu sẽ bao gồm dữ liệu mới. Nếu "cuối cùng" (không phân biệt chữ hoa chữ thường) hoặc nếu tham số này bị bỏ qua, thì dữ liệu trả về sẽ chỉ bao gồm dữ liệu cuối cùng.

Phản hồi

Kết quả được nhóm theo phương diện được chỉ định trong yêu cầu. Tất cả các giá trị có cùng một nhóm giá trị phương diện sẽ được nhóm vào một hàng duy nhất. Ví dụ: nếu bạn nhóm theo phương diện quốc gia, thì tất cả kết quả cho "usa" sẽ được nhóm lại với nhau, tất cả kết quả cho "mdv" sẽ được nhóm lại với nhau, v.v. Nếu bạn nhóm theo quốc gia và thiết bị, thì tất cả kết quả cho "usa, tablet" sẽ được nhóm lại. Tất cả kết quả cho "usa, mobile" sẽ được nhóm, v.v. Hãy xem tài liệu về báo cáo Phân tích tìm kiếm để tìm hiểu thông tin cụ thể về cách tính lượt nhấp, lượt hiển thị, v.v. và ý nghĩa của chúng.

Kết quả được sắp xếp theo số lượt nhấp, theo thứ tự giảm dần, trừ phi bạn nhóm theo ngày (trong trường hợp này, kết quả được sắp xếp theo ngày, theo thứ tự tăng dần (cũ nhất xếp trước, mới nhất cuối cùng). Nếu có sự ràng buộc giữa hai hàng, thì thứ tự sắp xếp là tuỳ ý.

Hãy xem thuộc tính rowLimit trong yêu cầu để tìm hiểu số lượng giá trị tối đa có thể được trả về.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}

Tên tài sản	Giá trị	Nội dung mô tả
`rows[]`	`list`	Danh sách các hàng được nhóm theo các khoá-giá trị theo thứ tự được cung cấp trong truy vấn.
`rows[].keys[]`	`list`	Danh sách giá trị phương diện cho hàng đó, được nhóm theo các phương diện trong yêu cầu, theo thứ tự được chỉ định trong yêu cầu.
`rows[].clicks`	`double`	Số lượt nhấp cho hàng.
`rows[].impressions`	`double`	Số lượt hiển thị cho hàng.
`rows[].ctr`	`double`	Tỷ lệ nhấp (CTR) cho hàng. Các giá trị nằm trong khoảng từ 0 đến 1, 0.
`rows[].position`	`double`	Vị trí trung bình trong kết quả tìm kiếm.
`responseAggregationType`	`string`	Cách Google tổng hợp kết quả.Xem tài liệu trợ giúp để tìm hiểu những điểm khác biệt giữa cách tính dữ liệu theo trang web và cách tính dữ liệu theo trang. Các giá trị được chấp nhận là: "`auto`" "`byPage`": Kết quả được tổng hợp theo trang. "`byProperty`": Kết quả được tổng hợp theo tài sản.

Hãy dùng thử!

Hãy sử dụng APIs Explorer (Trình khám phá API) bên dưới để gọi phương thức này trên dữ liệu trực tiếp và xem phản hồi.