推拉

总览

推拉式并非是最简单的集成方法,但它是最可靠的方法,这就是为什么我们推荐实施这种方法,尤其是当您处理大量数据时。

推拉式是一种异步集成方法。这意味着,提交作业后,我们将迅速返回一个包含作业信息(所有提交的作业参数和作业 ID,以及用于下载结果和检查作业状态的 URL)的 JSON。通过这种集成方法,作业提交过程完全独立于下载结果。

在我们处理完您的作业之后,如果您在提交作业时提供了一个 回调 URL,我们将 POST 一个包含更新作业信息的 JSON 有效载荷(包括作业的 status 设置为 done)到您的服务器。此时,您可以继续从我们的系统中下载结果。我们将结果保留在完成后至少 24 小时 内可供检索。

通过推拉式,您可以将您的结果直接上传到您的云存储 (AWS S3 或 Google 云存储)。

注意:如果您不想麻烦地设置一个接受传入回调通知的服务,则可以尝试每隔几秒钟就得到您的结果(这个概念叫做 轮询).

您也可以尝试通过 Postman 了解推拉式的工作原理。

单一作业

描述

下面这个端点只接受一个 queryurl 值。

端点

POST https://data.oxylabs.io/v1/queries

输入

您必须以 JSON 有效载荷发送您的作业参数,如以下代码示例所示:

curl --user user:pass1 \
'https://data.oxylabs.io/v1/queries' \
-H "Content-Type: application/json" \
 -d '{"source": "ENTER_SOURCE_HERE", "url": "https://www.example.com", "geo_location": "United States", "callback_url": "https://your.callback.url", "storage_type": "s3", "storage_url": "s3://your.storage.bucket.url"}'

输出

API 将响应一个包含作业信息的 JSON,具体如下:

{
  "callback_url": "https://your.callback.url",
  "client_id": 5,
  "context": [
    {
      "key": "results_language",
      "value": null
    },
    {
      "key": "safe_search",
      "value": null
    },
    {
      "key": "tbm",
      "value": null
    },
    {
      "key": "cr",
      "value": null
    },
    {
      "key": "filter",
      "value": null
    }
  ],
  "created_at": "2019-10-01 00:00:01",
  "domain": "com",
  "geo_location": "United States",
  "id": "12345678900987654321",
  "limit": 10,
  "locale": null,
  "pages": 1,
  "parse": false,
  "render": null,
  "url": "https://www.example.com",
  "source": "universal",
  "start_page": 1,
  "status": "pending",
  "storage_type": "s3",
  "storage_url": "YOUR_BUCKET_NAME/12345678900987654321.json",
  "subdomain": "www",
  "updated_at": "2019-10-01 00:00:01",
  "user_agent_type": "desktop",
  "_links": [
    {
      "rel": "self",
      "href": "http://data.oxylabs.io/v1/queries/12345678900987654321",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "http://data.oxylabs.io/v1/queries/12345678900987654321/results",
      "method": "GET"
    }
  ]
}

检查作业状态

描述

如果您在提交作业时包含一个有效的 callback_url 值。完成作业后,我们将POST 一个 JSON 有效载荷到您指定的回调 URL。JSON 有效载荷将表明作业已经完成,其状态设置为done

然而,如果您提交的作业没有callback_url,则可以自己检查作业状态。要做到这一点,使用 rel:self 中的 href URL,取自您提交作业后收到的响应信息。

检查作业状态的 URL 看起来与此类似:http://data.oxylabs.io/v1/queries/12345678900987654321。查询这个 URL 将返回作业信息,包括其status

可能的 status 值共有 3 种:

参数描述

pending

该作业仍在处理中,尚未完成。

done

作业完成后,您可以通过查询rel:results中的href URL 来检索结果,例如http://data.oxylabs.io/v1/queries/12345678900987654321/results

faulted

作业中出现了问题,我们无法完成。您不需要为任何错误作业负责。

端点

GET https://data.oxylabs.io/v1/queries/{id}

输入

curl --user user:pass1 \
'http://data.oxylabs.io/v1/queries/12345678900987654321'

输出

{
  "client_id": 5,
  "context": [
    {
      "key": "results_language",
      "value": null
    },
    {
      "key": "safe_search",
      "value": null
    },
    {
      "key": "tbm",
      "value": null
    },
    {
      "key": "cr",
      "value": null
    },
    {
      "key": "filter",
      "value": null
    }
  ],
  "created_at": "2019-10-01 00:00:01",
  "domain": "com",
  "geo_location": null,
  "id": "12345678900987654321",
  "limit": 10,
  "locale": null,
  "pages": 1,
  "parse": false,
  "render": null,
  "query": "adidas",
  "source": "google_shopping_search",
  "start_page": 1,
  "status": "done",
  "subdomain": "www",
  "updated_at": "2019-10-01 00:00:15",
  "user_agent_type": "desktop",
  "_links": [
    {
      "rel": "self",
      "href": "http://data.oxylabs.io/v1/queries/12345678900987654321",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "http://data.oxylabs.io/v1/queries/12345678900987654321/results",
      "method": "GET"
    }
  ]
}

API 将通过在响应主体中打印 JSON 格式响应查询信息。请注意,作业状态已被改变为status。您现在可以通过向 http://data.oxylabs.io/v1/queries/12345678900987654321/results 发送查询来检索内容。您还可以看到,该作业 updated_at 2019-10-01 00:00:15 - 作业花了 14 秒完成。

检索作业内容

描述

在知道可以准备检索作业后,您便可使用作业信息响应 rel:results 中的 href URL 来进行 GET。结果链接看起来像这样:http://data.oxylabs.io/v1/queries/12345678900987654321/results

通过设置回调 服务,无需定期检查作业状态即可自动检索结果 。要做到这一点,在提交作业时指定一个能够接受传入 HTTP 请求的服务器的 URL。当我们的系统完成作业时,它将寄送 一个 JSON 有效载荷到所提供的 URL,而回调服务将下载结果,正如在回调执行示例所示。

端点

GET https://data.oxylabs.io/v1/queries/{id}/results

输入

以下代码示例展示了如何使用/results端点。

curl --user user:pass1 \
'http://data.oxylabs.io/v1/queries/12345678900987654321/results'

输出

下面的 JSON 文件包含了一个 /results 端点的响应示例:

{
  "results": [
    {
      "content": "<!doctype html><html>
        CONTENT      
      </html>",
      "created_at": "2019-10-01 00:00:01",
      "updated_at": "2019-10-01 00:00:15",
      "page": 1,
      "url": "https://www.google.com/search?q=adidas&hl=en&gl=US",
      "job_id": "12345678900987654321",
      "status_code": 200
    }
  ]
}

回调

该回调是一个我们向您的机器发送的 POST 请求,通知您数据提取任务已经完成,并提供一个 URL 来下载抓取的内容。这意味着,您不再需要手动检查作业状态 。一旦数据到手,我们会通知您,您现在需要做的就是进行检索 。请查看 Python 和 PHP 的代码样本。

# This is a simple Sanic web server with a route listening for callbacks on localhost:8080.
# It will print job results to stdout.
import requests
from pprint import pprint
from sanic import Sanic, response


AUTH_TUPLE = ('user', 'pass1')

app = Sanic()


# Define /job_listener endpoint that accepts POST requests.
@app.route('/job_listener', methods=['POST'])
async def job_listener(request):
    try:
        res = request.json
        links = res.get('_links', [])
        for link in links:
            if link['rel'] == 'results':
                # Sanic is async, but requests are synchronous, to fully take
                # advantage of Sanic, use aiohttp.
                res_response = requests.request(
                    method='GET',
                    url=link['href'],
                    auth=AUTH_TUPLE,
                )
                pprint(res_response.json())
                break
    except Exception as e:
        print("Listener exception: {}".format(e))
    return response.json(status=200, body={'status': 'ok'})


if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)

样例回调输出

{  
   "created_at":"2019-10-01 00:00:01",
   "updated_at":"2019-10-01 00:00:15",
   "locale":null,
   "client_id":163,
   "user_agent_type":"desktop",
   "source":"google_shopping_search",
   "pages":1,
   "subdomain":"www",
   "status":"done",
   "start_page":1,
   "parse":0,
   "render":null,
   "priority":0,
   "ttl":0,
   "origin":"api",
   "persist":true,
   "id":"12345678900987654321",
   "callback_url":"http://your.callback.url/",
   "query":"adidas",
   "domain":"com",
   "limit":10,
   "geo_location":null,
   {...}
   "_links":[
      {  
         "href":"https://data.oxylabs.io/v1/queries/12345678900987654321",
         "method":"GET",
         "rel":"self"
      },
      {  
         "href":"https://data.oxylabs.io/v1/queries/12345678900987654321/results",
         "method":"GET",
         "rel":"results"
      }
   ],
}

批量查询

描述

爬虫API 支持在单批请求中提交多达 1,000 个 queryurl 参数值。

该系统将把每项 queryurl 都作为一个单独作业来处理。如果您提供一个回调 URL,则将获得每个关键词的单独调用。否则,我们的初始响应将包含所有关键词的作业 id。例如,如果您发送了 50 个关键词,我们将返 50 个独特的作业 id

重要事项:通过 /batch 端点,您只能提交queryurl参数值的列表(取决于您使用的 source)。所有其他参数都应该有单数值。

端点

POST https://data.oxylabs.io/v1/queries/batch

输入

您必须将查询参数作为 JSON 有效载荷发布。下面列出了提交批量作业的方式:

curl --user user:pass1 \
'https://data.oxylabs.io/v1/queries/batch' \
-H 'Content-Type: application/json' \
-d '@keywords.json'

您可能注意到,以上代码示例没有解释 JSON 有效载荷的格式化方式,而是指出了一个预先制作的 JSON 文件。下面是 keywords.json 文件的内容,其中包含多个 query 参数值:

{  
   "query":[  
      "adidas",
      "nike",
      "reebok"
   ],
   "source": "google_shopping_search",
   "domain": "com",
   "callback_url": "https://your.callback.url"
}

...而这里有一个keywords.json 批量输入文件,包含多个 URL:

{  
   "url":[  
      "https://example.com/url1.html",
      "https://example.com/url2.html",
      "https://example.com/url3.html"
   ],
   "source": "universal",
   "callback_url": "https://your.callback.url"
}

响应

API 将响应一个 JSON 对象,其中包含每项所创建作业的信息。回复类似于以下:

{
  "queries": [
    {
      "callback_url": "https://your.callback.url",
      {...}
      "created_at": "2019-10-01 00:00:01",
      "domain": "com",
      "id": "12345678900987654321",
      {...}
      "query": "adidas",
      "source": "google_shopping_search",
      {...}
          "rel": "results",
          "href": "http://data.oxylabs.io/v1/queries/12345678900987654321/results",
          "method": "GET"
        }
      ]
    },
    {
      "callback_url": "https://your.callback.url",
      {...}
      "created_at": "2019-10-01 00:00:01",
      "domain": "com",
      "id": "12345678901234567890",
      {...}
      "query": "nike",
      "source": "google_shopping_search",
      {...}
          "rel": "results",
          "href": "http://data.oxylabs.io/v1/queries/12345678901234567890/results",
          "method": "GET"
        }
      ]
    },
    {
      "callback_url": "https://your.callback.url",
      {...}
      "created_at": "2019-10-01 00:00:01",
      "domain": "com",
      "id": "01234567899876543210",
	  {...}
      "query": "reebok",
      "source": "google_shopping_search",
	  {...}
          "rel": "results",
          "href": "http://data.oxylabs.io/v1/queries/01234567899876543210/results",
          "method": "GET"
        }
      ]
    }
  ]
}

获取通知程序 IP 地址列表

描述

您可能想把向您发送回调信息的 IP 列入白名单,或为其他目的获得这些 IP 的列表。通过GET 这个端点即可:

端点

GET https://data.oxylabs.io/v1/info/callbacker_ips

输入

以下代码示例展示了如何访问 /callbacker_ips 端点:

curl --user user:pass1 \
'https://data.oxylabs.io/v1/info/callbacker_ips'

输出

API 将返回向您的系统发出回调请求的 IP 列表。

{
    "ips": [
        "x.x.x.x",
        "y.y.y.y"
    ]
}

上传到云存储器

描述

爬虫 API 作业结果存储在我们的存储库中。如上所述,您可以通过 GET /results 端点而从我们的存储中获得您的结果。

作为一种选择,我们可以将结果上传到您的云存储中。这样,您就不必发出额外请求来获取结果 - 所有内容都直接转到您的存储桶。

目前,我们支持 Amazon S3Google 云存储。如果您想使用不同存储类型,请联系您的客户经理以讨论功能交付时间表。

上传路径看起来像这样:YOUR_BUCKET_NAME/job_ID.json.您可以在提交作业后从我们收到的回复中找到作业 ID。在这个示例 作业 ID 是12345678900987654321

参数值

参数描述有效值

storage_type

您的云存储类型。

s3(AWS S3);gcs(Google 云存储)。

storage_url

您的云存储桶名称。

任何 s3gcs 云存储桶名称。

Amazon S3

To get your job results uploaded to your Amazon S3 bucket, please set up access permissions for our service. To do that, go to https://s3.console.aws.amazon.com/ > S3 > Storage > Bucket Name (if don't have one, create a new one) > Permissions > Bucket Policy

要将您的作业结果上传到您的 Amazon S3 桶,请为我们的服务设置访问权限。要做到这一点,请进入https://s3.console.aws.amazon.com/ > S3 > Storage > Bucket Name(如果没有,就创建一个新的桶)> Permissions > Bucket Policy

您可以在以下随附的桶策略或在代码示例区找到。

不要忘记在 YOUR_BUCKET_NAME 下修改桶的名称。这项策略允许我们写到您的桶,让您访问上传的文件,并知道桶的位置。

{
    "Version": "2012-10-17",
    "Id": "Policy1577442634787",
    "Statement": [
        {
            "Sid": "Stmt1577442633719",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::324311890426:user/oxylabs.s3.uploader"
            },
            "Action": "s3:GetBucketLocation",
            "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
        },
        {
            "Sid": "Stmt1577442633719",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::324311890426:user/oxylabs.s3.uploader"
            },
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
        }
    ]
}

Google Cloud Storage

为了将您的作业结果上传到您的 Google 云存储桶,请为我们的服务设置特殊权限。要做到这一点,请用 storage.objects.create 权限创建一个自定义角色,并将其分配给 Oxylabs 服务账户的电子邮件 oxyserps-storage@oxyserps-storage.iam.gserviceaccount.com.

Scheduler

Scheduler 是一项服务,您可以用来安排经常性抓取作业。

它扩展了推拉式集成的功能,最好与上传至存储器功能一起使用。

访问Scheduler”部分 以了解如何使用这一功能。

任务管家 (Scheduler)

Last updated