Greasy Fork

GM Requests

Imitating Python's Requests library based on GM_xmlHttpRequest.

当前为 2023-07-02 提交的版本，查看 最新版本。

此脚本不应直接安装。它是供其他脚本使用的外部库，要使用该库请加入元指令 // @require https://update.greasyfork.icu/scripts/470000/1214468/GM%20Requests.js

作者
大碗宽面wtw
版本
0.0.1
创建于
2023-07-02
更新于
2023-07-02
大小
23.7 KB
许可证
MIT

GM Requests

中文

Based on GM_xmlHttpRequest, GM Requests is a library that emulates Python's Requests library.

How to Import

Using @require tag in a script

// ==UserScript==
// @name         My Tampermonkey Script
// @description  Example script using the library
// @require      https://your-domain.com/path-to-your-library/my-library.js
// ==/UserScript==

requests.get('https://github.com');

Using import in local code

First, install GM Requests:

npm install https://github.com/bigbowl-wtw/GM-Requests.git

Import in your code:

import requests from 'gm-requests';

requests.get('https://github.com');

Usage

requests.get

let ret = await requests.get(
    'https://httpbin.org/get',
    { foo: 'bar' },
    { responseType: 'json' }
);

Function signature:

requests.get<TResolve = any, TContext = object>(
    url: string | URL,
    query?: Query,
    options?: Options<TContext>
): Promise<TResolve>

url: The URL of the request.

query: Query parameters to be sent.

options: Parameters passed to GM_xmlHttpRequest, excluding url, method, headers, and cookies.

requests.post

let ret = await requests.post(
    'https://httpbin.org/get',
    {
        data: { foo: 'bar' },
        responseType: 'json'
    }
);

Function signature:

requests.post<TResolve = any, TContext = object>(
    url: string | URL,
    options?: Options<TContext>
): Promise<TResolve>

url: The URL of the request.

options:

  • json?: any: An object that can be converted to a JSON string.
  • data: { [key: string]: string }: Data sent with 'application/x-www-form-urlencoded' encoding.
  • Other parameters that can be passed to GM_xmlHttpRequest, excluding url, method, headers, and cookies.

json and data only have an effect in post requests.

How to Use Headers and Cookies

Similar to requests, requests.get and requests.post can send requests with specified headers or cookies by including them in the options.

1. cookies:

requests.get('https://httpbin/get', { cookies: { foo: 'bar' } });

The above usage will generate the following cookie:

Cookie: foo=bar;

cookies is an object with string values, where the keys are the cookie names and the values are the cookie values:

type ICookieSet = {
    [name: string]: string;
};

Cookies: ICookieSet

The same cookie cannot have multiple values.

All cookies set via cookies will be appended after the cookies managed by the browser, as determined by GM_xmlHttpRequest.

2. headers:

requests.get('https://httpbin/get', { cookies: { foo: 'bar' } });

The above usage will generate the following header:

foo: bar

headers is an object with string or string[] values, where the keys are the header names and the values are the header values. When the value is a string[], it represents multiple values for the header, and they will be separated by commas when sending the request:

headers: {
    [header: string]: string | string[];
} & {
    cookie?: {
        [name: string]: string;
    };
}

3. Priority of headers.cookie and cookies

According to the behavior of GM_xmlHttpRequest, the priority is headers.cookie > cookies, and this library follows the same behavior.

Using Session

Similar to requests, Session is used to maintain custom cookies across requests. However, cookies set in the server response via the Set-Cookie header will be managed by the browser, and Session will not handle them. It will mark and delete them, and if the same named cookie is passed again in future requests, Session will ignore them.

let session = new requests.Session();

session.headers = { foo: 'bar' };
// header will be overwritten as { foo: 'com.github.bigbowl-wtw/gm-requests' }
session.headers.update({ foo: 'com.github.bigbowl-wtw/gm-requests' });
// header will be updated to { foo: [ 'com.github.bigbowl-wtw/gm-requests', 'bar' ]}
session.headers.append('foo', 'bar');

session.cookies = { test: 'A' };
session.cookie.update({ test: 'B' });

When headers contain cookies, Session.cookies will be updated (not Session.headers.cookie).

requests.session

requests.session returns a Session instance (equivalent to requests).

let session: requests.Session = requests.session();