Google SERP API 原始 HTML:检索并验证 rawUrl
Senior Web Scraping Engineer
精要摘要:
- metadata.rawUrl 指向已存储的 Google SERP HTML。 在收到完整的 JSON 响应后,再去抓取该 URL。
- HTML 获取是第二次 HTTP 请求。 搜索响应本身并不在该字段内嵌下载好的文档。
- 文档检查提供有限但有用的证据。 状态、媒体类型、字节数和结构有助于发现问题,但不能证明页面的每个特性都完整无缺。
- 保留原始字节和校验和。 本地副本可在远程存储链接不可用时独立检查。
引言:在解析结果背后保留原始页面
结构化搜索数据便于分析,但仅凭一个 JSON 字段无法展示其来源页面上的全部信息。存储下来的 HTML 文档在需要解释结果时提供了另一个可检查的层面。
Scrapeless Google Search API 可以在结构化结果旁返回 metadata.rawUrl。本篇 Google SERP API 原始 HTML 教程演示如何获取该文档并检查下载内容。目标是可审计的本地工件,而不是宣称保存的标记能重现在线浏览器页面的每一次交互。
Google Search 快速上手响应 展示了 metadata 下的该字段。更通用的执行请求模型会先提供搜索数据;HTML 下载随后进行。
rawUrl 表示什么
rawUrl 的值是与该响应关联的已存储页面文档的 URL。它不是自然搜索结果的最终目标 URL。
在概念上区分三个地址:接受搜索的 API 端点、已存储的 SERP HTML 地址,以及可能指向发布者页面的结果链接。下载 SERP 文档并不会获取每一篇被链接的文章、商品或商家页面。
不要从查询或任务 ID 构造存储路径。要从完成的响应中读取确切的 URL。存储位置是一个输出值,从文档示例中拷贝的地址并不能作为你自己请求的证据。
缺失的 rawUrl 应当在你的流程中变成显式的“HTML 不可用”状态。它不应被一个新构造的 Google 搜索 URL 所替代,因为那会触发一次不同的观测。
在下载 HTML 之前先获取 JSON
搜索任务必须完成后,HTML 获取程序才能读取其元数据。如果搜索返回 HTTP 201,请先使用任务结果工作流获取已完成的对象。
下面的脚本假定该对象已保存为 serp.json。其他前提条件是安装好 Python 和 Requests,可通过 python -m pip install requests 安装。将脚本保存为 fetch_serp_html.py,并在已保存的响应旁运行 python fetch_serp_html.py。
观测到的存储 URL 在 api.scrapeless.com 上使用 HTTPS,路径位于 /storage/ 之下。程序将下载限制在该观测到的主机和路径结构上,不跟随重定向,也不向存储发送 API 密钥头。将来若存储主机发生变化,应触发对规则的复审,而不是放宽为不受限制的抓取。
URL 检查需要分析各组成部分,而不是做子串匹配。URI 语法规范定义了该检查所用的 scheme、authority、path 等组成部分。
python
import hashlib
import json
from html.parser import HTMLParser
from pathlib import Path
from urllib.parse import urlsplit
import requests
class DocumentShape(HTMLParser):
def __init__(self):
super().__init__()
self.opened = set()
self.closed = set()
def handle_starttag(self, tag, attrs):
self.opened.add(tag)
def handle_endtag(self, tag):
self.closed.add(tag)
data = json.loads(Path("serp.json").read_text(encoding="utf-8"))
metadata = data.get("metadata")
raw_url = metadata.get("rawUrl") if isinstance(metadata, dict) else None
if not isinstance(raw_url, str) or not raw_url:
raise ValueError("metadata.rawUrl is absent")
parts = urlsplit(raw_url)
if (parts.scheme != "https" or parts.hostname != "api.scrapeless.com"
or parts.port not in (None, 443) or parts.username or parts.password
or not parts.path.startswith("/storage/")):
raise ValueError("Storage URL needs review before downloading")
# The storage fetch uses no API-key header and follows no redirects.
with requests.get(raw_url, timeout=(10, 60), stream=True, allow_redirects=False) as response:
response.raise_for_status()
if response.status_code != 200:
raise ValueError(f"Unexpected storage status: {response.status_code}")
media_type = response.headers.get("Content-Type", "").split(";")[0].lower()
if media_type not in ("text/html", "application/xhtml+xml"):
raise ValueError(f"Unexpected media type: {media_type}")
chunks = []
size = 0
for chunk in response.iter_content(65536):
size += len(chunk)
if size > 10 * 1024 * 1024:
raise ValueError("HTML exceeds this example's local size limit")
chunks.append(chunk)
html_bytes = b"".join(chunks)
if not html_bytes:
raise ValueError("Empty HTML body")
Path("serp.html").write_bytes(html_bytes)
shape = DocumentShape()
shape.feed(html_bytes.decode("utf-8", errors="replace"))
report = {
"bytes": len(html_bytes),
"sha256": hashlib.sha256(html_bytes).hexdigest(),
"has_html": "html" in shape.opened,
"has_body": "body" in shape.opened,
"has_closing_html": "html" in shape.closed,
"source_url": raw_url,
}
Path("serp-html-check.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
print(json.dumps({key: value for key, value in report.items() if key != "source_url"}))
本地的一千万字节(十 MiB)限制是客户端防护示例,而不是 API 的 HTML 最大尺寸。更大的文档意味着需要审视你预期的工作负载,并有意识地调整本地策略。程序只会在有限下载成功后才写出字节。
从 Scrapeless 开始抓取
使用 Scrapeless 提升你的网页抓取与自动化工作流。
立即注册即可获得 5 美元免费余额 —— 无需信用卡。现在就在 Scrapeless 控制面板领取你的免费额度。
在多个层面检查下载内容
有用的 HTML 检查需要记录传输是否成功、文档类型、载荷大小、结构,以及与原始搜索之间的对应关系。没有任何单一检查能证明以上全部内容。
本教程中使用的基线 coffee 响应导致了第二个请求,其返回 HTTP 200 和 Content-Type: text/html。下载内容为 1,938,204 字节,并且包含起始 html 和 body 元素以及一个结束 html 元素。这些是来自一个已存储文档的观察结果,而不是后续响应的最小大小要求。
| Check | 它所确认的内容 | 它未能确认的内容 |
|---|---|---|
| HTTP status | 存储请求按预期完成 | 文档包含预期结果 |
| Media type | 服务器将该表示识别为 HTML | 所有搜索功能都存在 |
| Nonempty bytes | 已下载响应体 | 响应体是正确的页面 |
| Document elements | 基本标记结构存在 | 语义完整性或渲染保真度 |
| Checksum | 后续字节可与保存的副本进行比较 | 页面上每条声明的真实性 |
| Query and result inspection | 文档与选定的响应细节相对应 | 所有可能搜索模块的完整性 |
响应首部和内容表示的含义由 HTTP 表示语义定义。应将 content-type 检查视为一个信号,而不是阅读文档的替代品。
Python 的 HTMLParser 接口可以识别标记事件。它不是浏览器渲染器,也不是完整的符合性验证器。因此,报告中的布尔结构字段仍然只是适度的检查。
检查 HTML 是否与搜索相匹配
对应性检查应将已存储的文档与请求及选定的返回记录进行比较。从页面上显示的查询和 JSON 中存在的一小部分标题或链接开始。
文本可能以实体编码形式出现,被拆分到多个元素中,或以嵌入数据中的不同形式表示。原始子串匹配失败是进一步检查文档的理由,而不是立即证明某个结果缺失的证据。如果在本地渲染文件,外部资源和脚本可能不可用,或可能请求当前资源,因此渲染效果可能与最初检索时不同。
使用保存的文档来回答一个具体的问题。例如,判断某个标题是否出现在标记中,是否存在意外的链接形式,或者该文档是否实际上是搜索页面。避免将这些观察上升为“每个动态扩展或隐藏模块都被捕获”的结论。
排查缺失或不可用的 HTML
HTML 问题应在其发生的步骤进行分类。即使存储抓取失败,也要保留已完成搜索的 JSON。
| Symptom | Check |
|---|---|
metadata 缺失 |
确认你已保存完成的搜索对象 |
rawUrl 缺失或为空 |
将该响应的 HTML 记录为不可用 |
| URL 被脚本拒绝 | 将实际存储源与已批准的源进行比较 |
| 非 200 存储响应 | 保留状态和请求上下文;不要将其标记为文档 |
| 意外的媒体类型 | 在将其视为 HTML 之前检查响应内容 |
| 达到大小限制 | 检查本地限制和预期文档大小 |
| 结构检查失败 | 检查字节内容;仅有合法解析并不充分 |
| 查询或结果不匹配 | 比较来自同一请求的已保存 JSON 和 HTML |
不要假定远程存储地址具有永久保留期。如果流程需要归档,应在文档仍可获取时将其下载。将 JSON、HTML、校验和以及采集上下文一起保存,以便其他工程师能够理解它们之间的关系。
结论:保留实际下载的内容
原始 HTML 工作流包含两个不同的操作:获取已完成的搜索 JSON,然后下载其存储的 HTML URL。保存文档,并记录能够精确说明观测结果的检查记录。
使用 Google Search API 参数 控制最初的查询,并在规划搜索工作量时参考当前定价。在你自己的报告中,将 HTML 可用性与自然结果可用性区分开来。
构建你的搜索数据工作流
加入在社区中使用搜索数据的开发者: Discord · Telegram。
创建一个 Scrapeless 账号,并先将本教程应用于一小组查询,再计划更大规模的采集。
常见问题
问:rawUrl 是否包含 HTML 文本?
不。它包含一个 URL。第二个 HTTP 请求会下载该文档。
问:rawUrl 是自然结果的最终目标地址吗?
不是。它指向与该响应关联的已存储 SERP 文档,而不是指向该 SERP 上列出的每个网站。
问:闭合的 html 标签能证明整个 SERP 已经完整了吗?
不能。它只是一个结构信号。内容对应性和动态功能的完整性需要进行额外检查。
问:存储请求应该包含 API 密钥吗?
观察到的存储下载在没有认证头的情况下也成功了。此示例将密钥仅限制在 API 请求中,不会将其转发到存储服务或结果网站。
问:存储的 HTML 链接是永久存档吗?
不要假设尚未确定的保留保证。当以后需要该文档时,请保留本地副本并计算校验和。
问:已保存的 HTML 可以替代目标页面验证吗?
不能。SERP HTML 记录的是搜索结果页。对链接页面内容的验证是一个单独的任务。
在Scrapeless,我们仅访问公开可用的数据,并严格遵循适用的法律、法规和网站隐私政策。本博客中的内容仅供演示之用,不涉及任何非法或侵权活动。我们对使用本博客或第三方链接中的信息不做任何保证,并免除所有责任。在进行任何抓取活动之前,请咨询您的法律顾问,并审查目标网站的服务条款或获取必要的许可。



