SuperAgent – ​​elegante API für AJAX in Node und Browsern (2023)

SuperAgent ist eine leichte progressive Ajax-API mit Flexibilität, Lesbarkeit und geringer Lernkurve. Es funktioniert auch mit Node.js!

request .post('/api/pet') .send({ Name: 'Manny', Species: 'cat' }) .set('X-API-Key', 'foobar') .set('Accept', 'application/json') .then(res => { Alert('yay got ' + JSON.stringify(res.body)); });

Testdokument

Englisch

die folgendeTestdokumentwird eingesetztMokkaDer „Dokumentations“-Reporter generiert die Testsuite und spiegelt sie direkt wider. Dies stellt eine zusätzliche Dokumentationsquelle dar.

Grundanforderung

kann per Anruf erreicht werdenAnfrageGeeignete Methode für das Objekt, um die Anforderung zu stellen, und dann aufrufen.Dann()( oder.Ende()odererwarten)Anfrage senden. Zum Beispiel ein einfachesERHALTENfragen:

request .get('/search') .then(res => { // res.body, res.headers, res.status }) .catch(err => { // err.message, err.response });

HTTP-Methoden können auch als Strings übergeben werden:
Anmerkung des Übersetzers: Groß- und Kleinschreibung sind zulässig.

request('GET', '/search').then(success, failed);

Rückrufe im alten Stil werden ebenfalls unterstützt, sind jedoch veraltet. Du kannst anrufen.Ende() ersetzen .Dann()::

request('GET', '/search').end(function(err, res){ if (res.ok) {}});

Es können absolute URLs verwendet werden. In Webbrowsern werden absolute URLs nur auf dem Server implementiertCORSnur gültig.

request .get('https://example.com/search') .then(res => { });

KnotenKundenbetreuung zuUnix-Domänen-SocketsEine Anfrage stellen:

// Muster: https?+unix://SOCKET_PATH/REQUEST_PATH// „%2F“ im Socket-Pfad als „/“ verwenden try { const res = waiting request .get('http+unix://% 2Fabsolute%2Fpath% 2Fto%2Funix.sock/search'); // res.body, res.headers, res.status} Catch(err) { // err.message, err.response}

DELETE__、__HEAD__、__PATCH__、__POSTUndSETZENAnfragen funktionieren auch, ändern Sie einfach den Methodennamen:

request .head('/favicon.ico') .then(res => { });

LÖSCHENkann auch benutzt werden.des()Aus Gründen der Kompatibilität mit älteren IE-Versionen aufgerufen, wolöschenist ein reserviertes Wort.

Die HTTP-Methode ist standardmäßig __GET__, daher ist der folgende Code gültig, wenn Sie dies bevorzugen:

request('/search', (err, res) => { });

Verwenden Sie HTTP/2

Um das HTTP/2-Protokoll (ohne HTTP/1.x-Fallback) zu verwenden, verwenden Sie.http2()Methode.

const request = require('superagent'); const res = auf Anfrage warten .get('https://example.com/h2') .http2();

Legen Sie Anforderungsheaderfelder fest

Das Festlegen von Anforderungsheaderfeldern ist einfach: Rufen Sie an.Satz()Bei der Übergabe von Feldnamen und -werten:

request .get('/search') .set('API-Key', 'foobar') .set('Accept', 'application/json') .then(callback);

Sie können auch ein Objekt übergeben, um mehrere Felder in einem Aufruf festzulegen:

request .get('/search') .set({ 'API-Key': 'foobar', Accept: 'application/json' }) .then(callback);

ERHALTENfragen

.Anfrage()Methode akzeptiert ein Objekt und bei Verwendung mitERHALTENMethoden bilden zusammen eine Abfragezeichenfolge. Im Folgenden wird der Pfad generiert/search?query=Manny&range=1..5&order=desc. Anmerkung des Übersetzers:.Anfrage()Die Parameter der Methode müssen nicht vorab url-kodiert werden.

request .get('/search') .query({ query: 'Manny' }) .query({ range: '1..5' }) .query({ order: 'desc' }) .then(res = > { });

oder ein einzelnes Objekt übergeben:

request .get('/search') .query({ query: 'Manny', range: '1..5', order: 'desc' }) .then(res => { });

.Anfrage()Methoden können auch Zeichenfolgen akzeptieren.

request .get('/querystring') .query('search=Manny&range=1..5') .then(res => { });

Oder schließen Sie sich ihnen einzeln an:

request .get('/querystring') .query('search=Manny') .query('range=1..5') .then(res => { });

KOPFfragen

Sie können auch hinzufügenKOPFAnfragen verwenden die Methode .query(). Im Folgenden wird der Pfad generiert/users?email=joe@smith.com。

request .head('/users') .query({ email: 'joe@smith.com' }) .then(res => { });

POST/SETZENfragen

Ein typisches JSONPOSTEine Anfrage könnte so aussehen, wobei wir das entsprechend festlegenInhaltstypHeader-Felder und „schreiben“ einige Daten, in diesem Fall nur eine JSON-Zeichenfolge.

request.post('/user') .set('Content-Type', 'application/json') .send('{"name": "tj", "pet": "tobi"}') .then( Rückruf) .catch(errorCallback)

Da JSON zweifellos am häufigsten vorkommt, ist dies der FallStandardvon! Das folgende Beispiel entspricht dem vorherigen Beispiel.

request.post('/user') .send({ name: 'tj', pet: 'tobi' }) .then(callback, errorCallback)

oder mehrere anrufen.schicken()::

request.post('/user') .send({ name: 'tj' }) .send({ pet: 'tobi' }) .then(callback, errorCallback)

Standardmäßig wird eine Zeichenfolge gesendetInhaltstypFestlegen alsapplication/x-www-form-urlencoded, werden mehrere Anrufe mit getätigt&Verbindung, hier generiertname=tj&pet=tobi::

request.post('/user') .send('name=tj') .send('pet=tobi') .then(callback, errorCallback);

Das SuperAgent-Format ist erweiterbar, unterstützt jedoch standardmäßig „json“ und „form“. um die Daten zu übergeben alsapplication/x-www-form-urlencodedZum Versenden genügt ein Anruf.Typ()„form“ wird übergeben, der Standardwert ist „json“. DasPOSTDer Anfragetext lautet „name=tj&pet=tobi“.

request.post('/user') .type('form') .send({ name: 'tj' }) .send({ pet: 'tobi' }) .then(callback, errorCallback)

Unterstützt auch das SendenFormulardatenObjekt. Das folgende Beispiel wirdPOSTFordern Sie den Inhalt des durch id="myForm" identifizierten HTML-Formulars an:

request.post('/user') .send(new FormData(document.getElementById('myForm'))) .then(callback, errorCallback)

aufstellenInhaltstyp

Die offensichtliche Lösung ist die Verwendung.Satz()Methode:

request.post('/user') .set('Content-Type', 'application/json')

.Typ()Die Methode ist auch als Kurzschrift verfügbar und akzeptiert die Kanonisierung mit Typ/SubtypMime TypName oder nur die Erweiterung, z. B. „xml“, „json“, „png“ usw.:

request.post('/user') .type('application/json') request.post('/user') .type('json') request.post('/user') .type('png')

Serialisieren Sie den Anforderungstext

SuperAgent serialisiert JSON und Formulare automatisch. Sie können die automatische Serialisierung auch für andere Typen einrichten:

request.serialize['application/xml'] = function (obj) { return 'string generic from obj';};// Als nächstes werden alle Anfragen mit dem Inhaltstyp „application/xml“ automatisch serialisiert

Wenn Sie den Datenkörper (Nutzlast) in einem benutzerdefinierten Format senden möchten, können Sie den integrierten Serialisierer auf Anfragebasis durch ersetzen.serialize()Methode:

request .post('/user') .send({foo: 'bar'}) .serialize(obj => { return 'string generic from obj'; });

Wiederholungsanforderung

Wenn die Anfrage vorübergehend fehlschlägt oder möglicherweise aufgrund einer instabilen Netzwerkverbindung und wenn gegeben.wiederholen()Methode wiederholt SuperAgent die Anfrage automatisch.

Diese Methode verfügt über zwei optionale Parameter: die Anzahl der Wiederholungsversuche (standardmäßig).1) und eine Callback-Funktion. Es ruft vor jedem Wiederholungsversuch callback(err, res) auf. Rückruf kann zurückkommenWAHR/FALSCHum zu steuern, ob die Anfrage wiederholt werden soll (es sollte jedoch immer die maximale Anzahl von Wiederholungen verwendet werden). request.get('https://example.com/search') .retry(2) // oder: .retry(2, callback) // entweder .then(finished); .catch(failed);

.wiederholen()nur verwenden füridempotentAnfragen (d. h. mehrere Anfragen, die den Server erreichen, ohne unerwünschte Nebenwirkungen wie Doppelkäufe).

Standardmäßig werden alle Anforderungsmethoden ausprobiert (das heißt, Sie müssen eine benutzerdefinierte Wiederholungsrückruffunktion übergeben, wenn Sie nicht möchten, dass POST-Anfragen erneut versucht werden).

Die folgenden Statuscodes werden standardmäßig wiederholt:

• 408
• 413
• 429
• 500
• 502
• 503
• 504
• 521
• 522
• 524

Die folgenden Fehlercodes werden standardmäßig wiederholt:

• 'ETIMEDOUT'
• 'ECONNRESET'
• 'EADDRINUS'
• 'ECONNREFUSED'
• 'EPIPE'
• 'ENOTFOUND'
• 'ENETUNREACH'
• 'EAI_AGAIN'

Legen Sie „Akzeptieren“ fest

Und.Typ()Die Methode ist ähnlich und Sie können auch die Kurzschriftmethode verwenden.akzeptieren()aufstellenAkzeptierenAnforderungsheader. Der Einfachheit halber wird auch zitiertrequest.types, sodass Sie das Ganze normalisieren könnenMime TypName angegeben alsTyp/Subtyp, oder geben Sie die erweiterte Suffixform als „xml“, „json“, „png“ usw. an:

request.get('/user') .accept('application/json') request.get('/user') .accept('json') request.post('/user') .accept('png')

Facebook und JSON akzeptieren

Wenn Sie die API von Facebook aufrufen, senden Sie unbedingt dieAkzeptieren: application/jsonAnforderungsheader. Wenn Sie dies nicht tun, wird Facebook antwortenInhaltstyp: Text/Javascript; Zeichensatz=UTF-8, SuperAgent wird also nicht analysierenres.körperwird undefiniert sein. du kannst es benutzenreq.accept('json')oderreq.header('Accept', 'application/json')um dies zu tun. Weitere Informationen finden Sie unterHeft 1078。

Abfragezeichenfolgen

req.query(obj)ist eine Methode, die zum Erstellen von Abfragezeichenfolgen verwendet werden kann. Zum Beispiel inPOSTZunahme?format=json&dest=/login::

request .post('/') .query({ format: 'json' }) .query({ dest: '/login' }) .send({ post: 'data', hier: 'wahoo' }) .then (Ruf zurück);

Standardmäßig werden Abfragezeichenfolgen nicht in einer bestimmten Reihenfolge zusammengestellt. Kann benutzenreq.sortQuery()Abfragezeichenfolge zur Aktivierung der ASCII-basierten Sortierung. Sie können auch verwendenreq.sortQuery(myComparisonFn)Bietet benutzerdefinierte Sortiervergleichsfunktionen. Die Vergleichsfunktion sollte zwei Argumente akzeptieren und eine negative/null/positive Ganzzahl zurückgeben.

// Standardreihenfolge request.get('/user') .query('name=Nick') .query('search=Manny') .sortQuery() .then(callback) // Benutzerdefinierte Sortierfunktion request.get( ' /user') .query('name=Nick') .query('search=Manny') .sortQuery((a, b) => a.length - b.length) .then(callback)

TLS-Optionen

In Node.js unterstützt SuperAgent Methoden zum Konfigurieren von HTTPS-Anfragen:

• .ca(): Stellen Sie das CA-Zertifikat als vertrauenswürdig ein
• .cert(): Client-Zertifikatkette festlegen
• .Taste(): Privatschlüssel des Clients festlegen
• .pfx(): Legen Sie den PFX- oder PKCS12-codierten privaten Schlüssel und die Zertifikatskette des Clients fest
• .disableTLSCerts(): Abgelaufene oder ungültige TLS-Zertifikate nicht ablehnen. intern eingestelltRejectUnauthorized=true。Beachten Sie, dass diese Methode Man-in-the-Middle-Angriffe ermöglicht.

Weitere Informationen finden Sie unter Node.jshttps.Request-Dokumentation。

var key = fs.readFileSync('key.pem'), cert = fs.readFileSync('cert.pem');request .post('/client-auth') .key(key) .cert(cert) .then (Ruf zurück);

var ca = fs.readFileSync('ca.cert.pem');request .post('https://localhost/private-ca-server') .ca(ca) .then(res => {});

Analysieren des Antworttextes

SuperAgent analysiert für Sie bekannte Antworttextdaten, was derzeit unterstützt wirdapplication/x-www-form-urlencoded，application/json,ebenso gut wieMultipart-/Formulardaten. Sie können die automatische Analyse anderer Antworttextdaten einrichten:

//Browser request.parse['application/xml'] = function (str) { return {'object': 'parsed from str'};};//noderequest.parse['application/xml'] = function (res , cb) { // Antworttext analysieren und res.body hier festlegen cb(null, res); }; // Als nächstes werden Antworten vom Typ „application/xml“ automatisch analysiert

du kannst es benutzen.buffer(true).parse(fn)Methode zum Festlegen eines benutzerdefinierten Parsers (anstelle der integrierten Parser). Wenn die Antwortpufferung nicht aktiviert ist (.buffer(false)), wird es ausgelöstAntwortEreignis, ohne auf den Abschluss des Body-Parsers zu warten, alsoAntwortkörperwird nicht verfügbar sein.

JSON / Urlencodiert

Attributeres.körperist das analysierte Objekt, z. B. wenn die Anfrage mit der JSON-Zeichenfolge „{“user“:{“name“: „tobi“}}“ geantwortet hatres.body.user.namewird „tobi“ sein. Ebenso führt ein x-www-form-urlencoded-Wert von „user[name]=tobi“ zum gleichen Ergebnis. Es wird nur eine Verschachtelungsebene unterstützt. Wenn Sie komplexere Daten benötigen, senden Sie bitte stattdessen JSON.

Senden Sie ein Array mit wiederholten Schlüsseln..send({color: ['red','blue']})werde sendenFarbe=Rot&Farbe=Blau. Wenn Sie möchten, dass die Namen der Array-Schlüssel enthalten sind[], müssen Sie es selbst hinzufügen, da SuperAgent es nicht automatisch hinzufügt.

Mehrteilig

Knoten-Client überBeeindruckendDas Modul unterstützt _multipart/form-data_. Beim Parsen einer mehrteiligen Antwort das Objektres.filessteht Ihnen ebenfalls zur Verfügung. Angenommen, eine Anfrage antwortet mit dem folgenden mehrteiligen Anfragetext:

--whoopContent-Disposition: Anhang; name="Bild"; filename="tobi.png"Content-Type: image/png... Daten hier ...--whoopContent-Disposition: form-data; name="name"Content-Type: text/plainTobi--whoop--

res.body.namewird den Wert „Tobi“ haben undres.files.imageWird als dienenDateiObjekt.

Binärdaten

In einem Browser können Sie verwenden.responseType('blob')um die Verarbeitung binärer Antworttexte anzufordern. Diese API ist bei der Ausführung in node.js nicht erforderlich. Die unterstützten Parameterwerte für diese Methode sind

• 'Klecks'Den XmlHTTPRequests zugewiesenAntworttypAttribute
• 'Arraybuffer'Dem Attribut „responseType“ von XmlHTTPRequest zugewiesen

req.get('/binary.data') .responseType('blob') .then(res => { // res.body wird der browsereigene Blob-Typ sein });

Weitere Informationen finden Sie im Mozilla Developer Networkxhr.responseType-Dokumentation。

Antworteigenschaften

existierenAntwortFür das Objekt werden eine Reihe nützlicher Flags und Eigenschaften festgelegt, darunter Antworttext, analysierter Antworttext, Antwortheaderfelder, Statusflags und mehr.

Antworttext

res.textDie Eigenschaft enthält eine nicht analysierte Antworttextzeichenfolge. Diese Eigenschaft ist in der Client-API immer vorhanden und nur standardmäßig, wenn der Mime-Typ des Knotens mit „text/“ übereinstimmt.„、“/json“ oder „x-www-form-urlencoded“. Der Grund besteht darin, Speicher zu sparen, da das Puffern von Text für große Textkörper (z. B. mehrteilige Dateien oder Bilder) äußerst ineffizient ist. Informationen zum Erzwingen des Pufferns finden Sie unter „Pufferantwort"Teil.

Antwortkörper

So wie SuperAgent Anforderungsdaten automatisch serialisieren kann, kann er auch den Antworttext automatisch analysieren. Es wird analysiert, wenn ein Resolver für einen Inhaltstyp definiert wird, der standardmäßig „application/json“ und „application/x-www-form-urlencoded“ enthält. Dann kannst du bestehenres.körperAnalysiertes Objekt abrufen.

Antwort-Header-Feld

res.headerEin Objekt, das die geparsten Antwort-Header-Felder enthält, wobei die Feldnamen wie ein Knoten in Kleinbuchstaben geschrieben sind. Zum Beispielres.header['content-length']。

Antwortinhaltstyp (Content-Type)

Der Content-Type-Antwortheader ist ein Sonderfallres.typ, das keinen Zeichensatz hat (und einen haben kann). Beispiel: „text/html; charset=utf8“Inhaltstypwird „text/html“ bereitstellen alsres.typ,Dannres.charsetDas Attribut enthält „utf8“.

Antwortstatus

Antwortstatus-Flags helfen zusammen mit anderen nützlichen Informationen festzustellen, ob die Anfrage erfolgreich war, wodurch SuperAgent ideal für die Interaktion mit RESTful-Webdiensten geeignet ist. Diese Flags sind derzeit definiert als:

Var-Typ = Status / 100 | 0; // Status / Klasse res.status = Status; res.statusType = Typ; // Grundlagen res.info = 1 == type; res.ok = 2 == Typ; res.clientError = 4 == type; res.serverError = 5 == type; res.error = 4 == Typ || 5 == Typ; // 语法糖 res.accepted = 202 == status; res.noContent = 204 == Status || 1223 == Status; res.badRequest = 400 == Status; res.unauthorized = 401 == Status; res.notAcceptable = 406 == Status; res.notFound = 404 == Status; res.forbidden = 403 == Status;

Abbruchanforderung

Um eine Anfrage abzubrechen, rufen Sie einfach anreq.abort()Methode.

Timeout-Einstellung

Manchmal bleiben Netzwerke und Server „stecken“ und antworten nie, nachdem sie eine Anfrage angenommen haben. Legen Sie eine Zeitüberschreitung fest, um zu vermeiden, dass Anfragen ewig warten.

• req.timeout({deadline:ms})oderreq.timeout(ms)(InMSist Millisekunden > 0) legt eine Frist für den Abschluss der gesamten Anfrage (einschließlich aller Uploads, Weiterleitungen, Serververarbeitungszeit) fest. Wenn die Antwort innerhalb dieser Zeit nicht vollständig heruntergeladen wird, wird die Anfrage abgebrochen.

• req.timeout({response:ms})Legt die maximale Zeit fest, die auf das Eintreffen des ersten Bytes vom Server gewartet werden soll, begrenzt jedoch nicht die Dauer des gesamten Downloads. Das Antwort-Timeout sollte mindestens ein paar Sekunden länger sein als die Zeit, die der Server benötigt, um zu antworten, da es auch Zeit für DNS-Suchen, TCP/IP- und TLS-Verbindungen und das Hochladen der angeforderten Daten umfasst.

Sie sollten beide verwendenTerminUndAntwortAuszeit. Auf diese Weise können Sie ein kurzes Antwort-Timeout nutzen, um nicht reagierende Netzwerke schnell zu erkennen, und eine lange Cutoff-Zeit, um Zeit für Downloads in langsamen, aber zuverlässigen Netzwerken zu schaffen. Beachten Sie, dass beide Timer die zulässige Zeit begrenzenhochladenBindungszeit. Wenn Sie eine Datei hochladen, verwenden Sie eine lange Zeitüberschreitung.

request .get('/big-file?network=slow') .timeout({ Antwort: 5000, // 5 Sekunden warten, bis der Server mit dem Senden beginnt Frist: 60000, // aber 1 Minute warten, bis die Datei vollständig geladen ist . }) . then(res => { /* rechtzeitige Antwort */ }, err => { if (err.timeout) { /* timeout! */ } else { /* andere Fehler */ } });

Es liegt ein Timeout-Fehler vor.AuszeitAttribute.

verifizieren

Verfügbar sowohl im Node als auch im Browser über.auth()Methode zur Authentifizierung:

request .get('http://local') .auth('tobi', 'learnboost') .then(callback);

existierenKnotenIm Client kann die Basisauthentifizierung als „user:pass“ in die URL geschrieben werden:

request.get('http://tobi:learnboost@local').then(callback);

Standardmäßig ist nur dieBasicAuthentifizierung. In einem Browser können Sie hinzufügen{type:'auto'}So aktivieren Sie alle im Browser integrierten Methoden (Digest, NTLM usw.):

request.auth('digest', 'secret', {type:'auto'})

AutorMethode unterstützt auch aTrägertyp, um die tokenbasierte Authentifizierung anzugeben:

request.auth('my_token', { type: 'bearer' })

Folgen Sie der Weiterleitung

Standardmäßig werden bis zu 5 Weiterleitungen verfolgt, Sie können diese jedoch verwendenres.redirects(n)Methode, um es anzugeben:

const Antwort = Warten auf request.get('/some.png').redirects(2);

Weiterleitungen, die das Limit überschreiten, gelten als Fehler. verwenden.ok(res => res.status < 400)Lesen Sie sie als Erfolgsantworten.

globaler Staatsagent

Cookies speichern

SuperAgent speichert standardmäßig keine Cookies in Node, Sie können sie jedoch verwenden.Agent()Die Methode erstellt eine Kopie des SuperAgents, der das Cookie enthält. Jede Kopie verfügt über einen separaten Cookie-Speicher.

const agent = request.agent();agent .post('/login') .then(() => { return agent.get('/cookied-page'); });

In Browsern werden Cookies automatisch vom Browser verwaltet, also.Agent()Cookies werden nicht getrennt.

Standardoptionen für mehrere Anfragen

Die normale Anforderungsmethode, die auf einem Agenten aufgerufen wird, wird als Standard für alle von diesem Agenten gestellten Anforderungen verwendet.

const agent = request.agent() .use(plugin) .auth(shared); waiting agent.get('/with-plugin-and-auth'); // mit Plugin und Authentifizierung wait agent.get(' /also -with-plugin-and-auth'); // auch mit Plugin und Authentifizierung

Die vollständige Liste der Methoden, die der Proxy zum Festlegen von Standardwerten verwenden kann, ist:verwenden、An、einmal、Satz、Anfrage、Typ、akzeptieren、Autor、withCredentials、sortQuery、wiederholen、OK、Weiterleitungen、Auszeit、Puffer、serialisieren、analysieren、ca、Taste、pfx、zert.

Pipeline-Daten

Mit dem Node-Client können Sie Daten in und aus Anfragen weiterleiten. Beachten Sie, dass mit.Rohr() ersetzen .end()/.then()Methode.

Der Inhalt der Pipeline-Datei als Beispielanfrage:

const request = require('superagent');const fs = require('fs');const stream = fs.createReadStream('path/to/my.json');const req = request.post('/somewhere') ;req.type('json');stream.pipe(req);

Beachten Sie, dass beim Senden von Anforderungen über die Pipeline der Superagent verwendet wirdChunked-Transfer-KodierungSenden Sie weitergeleitete Daten, die nicht von allen Servern unterstützt werden (z. B. Python-WSGI-Server).

oder leiten Sie die Antwort an eine Datei weiter:

const stream = fs.createWriteStream('path/to/my.json');const req = request.get('/some.json');req.pipe(stream);

Sie können Pipes und Callback-Funktionen oder Promises nicht mischen. Beachten Sie, dass Siesollte nichtVersuchen Sie es mit Rohrleitungen.Ende()oderAntwortObjektergebnis:

// Tun Sie dies nicht: const stream = getAWritableStream(); const req = request .get('/some.json') // SCHLECHT: Dies leitet nutzlose Informationen in den Stream weiter und schlägt auf unerwartete Weise fehl .end((err , this_does_not_work) => this_does_not_work.pipe(stream)) const req = request .get('/some.json') .end() // BAD: Dies wird auch nicht unterstützt, Aufruf nach .end. Pipe. .pipe(nope_its_too_late);

im Superagentenzukünftige Versionrein, jaRohr()Unsachgemäße Aufrufe von schlagen fehl.

mehrteilige Anfrage

SuperAgent eignet sich auch hervorragend fürBauenes bietet Methode.anfügen()Und.Feld()mehrteilige Anfragen für .

wenn Sie es verwenden.Feld()oder.anfügen(), können Sie das nicht verwenden.schicken()Und dukann nichtaufstellenInhaltstyp(stellt den richtigen Typ für Sie ein).

Zusätzliche Dokumente

Um Dateien zu senden, verwenden Sie.attach(Name, [Datei], [Optionen]). Sie können dies tun, indem Sie mehrmals anrufen.anfügenum mehrere Dateien anzuhängen. Die Parameter sind:

• Name— Formular Der Feldname im Formular.
• Datei— eine Zeichenfolge mit einem Dateipfad oderBlob/PufferObjekt.
• Optionen– (optional) eine Zeichenfolge für einen benutzerdefinierten Dateinamen oder{Dateiname: Zeichenfolge}Objekt. Wird auch in Node unterstützt{contentType: 'mime/type'}. Erstellen Sie einen Browser mit dem entsprechenden TypKlecks。

request .post('/upload') .attach('image1', 'path/to/felix.jpeg') .attach('image2', imageBuffer, 'luna.jpeg') .field('caption', 'My.jpeg') cats') .then(callback);

Feldwert

Ähnlich wie Formularfelder in HTML können Sie diese verwenden.field(Name, Wert)Und.field({name: value})Legen Sie den Feldwert fest. Angenommen, Sie möchten einige Bilder mit Ihrem Namen und Ihrer E-Mail-Adresse hochladen. Ihre Anfrage könnte so aussehen:

request .post('/upload') .field('user[name]', 'Tobi') .field('user[email]', 'tobi@learnboost.com') .field('friends[]', ['loki', 'jane']) .attach('image', 'path/to/tobi.png') .then(callback);

Kompression

Der Node-Client unterstützt komprimierte Antworten und das Beste ist: Sie müssen nichts tun! Es funktioniert einfach.

Pufferantwort

Um zu erzwingen, dass der Antworttext als gepuffert wirdres.text, Du kannst anrufenreq.buffer(). Um die Standardpufferung von Textantworten (z. B. „text/plain“, „text/html“ usw.) aufzuheben, können Sie aufrufenreq.buffer(false)。

wenn der Puffer zur Verfügung stehtres.gepuffertMit diesem Flag können Sie sowohl gepufferte als auch ungepufferte Antworten im selben Rückruf verarbeiten.

CORS

Aus Sicherheitsgründen blockieren Browser Cross-Origin-Anfragen, es sei denn, der Server entscheidet sich für die Verwendung von CORS-Headern. Der Browser gibt außerdem eine zusätzliche Meldung ausOPTIONENAnfrage, um zu prüfen, welche HTTP-Header und -Methoden vom Server zugelassen sind.Lesen Sie mehr über CORS。

.withCredentials()Die Methode unterstützt das Senden von Cookies vom Ursprung, jedoch nur, wenn Access-Control-Allow-OriginNEINPlatzhalter ("*") undZugangskontrolle-Zulassen-Anmeldeinformationenwenn „wahr“.

request .get('https://api.example.com:4001/') .withCredentials() .then(res => { Assert.equal(200, Res.Status); Assert.Equal('tobi', Res .text); })

Fehlerbehandlung

Ihrer Rückruffunktion werden immer zwei Parameter übergeben: Fehler und Antwort. Wenn keine Fehler auftreten, wird das erste Argument verwendetNull::

request .post('/upload') .attach('image', 'path/to/tobi.png') .then(res => { });

Außerdem wird ein „Fehler“-Ereignis ausgelöst, auf das Sie warten können:

request .post('/upload') .attach('image', 'path/to/tobi.png') .on('error', handle) .then(res => { });

Bitte beachten Sie,Standardmäßig betrachtet Superagent 4xx- und 5xx-Antworten (und nicht behandelte 3xx-Antworten) als Fehler. Zum Beispiel, wenn Sie erhalten304 Nicht geändert、403 Verbotenoder500 Interner ServerBei der Fehlerantwort werden diese Statusinformationen durch den weitergeleitetFehlerstatusliefern. Fehler aus solchen Antworten enthalten auch aFehlerantwortFeld, das enthält „AntworteigenschaftenAlle in „erwähnten Eigenschaften“. Die Bibliothek funktioniert auf diese Weise, um den häufigen Fall zu behandeln, dass eine erfolgreiche Antwort erforderlich ist und ein HTTP-Fehlerstatuscode als Fehler behandelt wird, während dennoch benutzerdefinierte Logik für bestimmte Fehlerbedingungen möglich ist.

Netzwerkausfälle, Zeitüberschreitungen und andere nicht reagierende Fehler werden nicht berücksichtigtFehlerstatusoderFehlerantwortFeld.

Wenn Sie 404- oder andere HTTP-Fehlerantworten verarbeiten möchten, können Sie eine Abfrage durchführenFehlerstatusAttribute. Wenn ein HTTP-Fehler (4xx- oder 5xx-Antwort) auftritt,Res.FehlerAttribut ist einFehlerObjekt, mit dem Sie die folgenden Prüfungen durchführen können:

if (err && err.status === 404) { Alert('oh no ' + res.body.message);}else if (err) { // alle anderen Fehlertypen, die behandelt werden müssen}

Alternativ können Sie verwenden.ok(Rückruf)Methode, um festzustellen, ob die Antwort ein Fehler ist.OKDie Callback-Funktion der Funktion ruft die Antwort ab und gibt true zurück, wenn die Antwort als Erfolg interpretiert werden soll.

request.get('/404') .ok(res => res.status < 500) .then(response => { // 404-Seite als erfolgreiche Antwort abrufen })

Fortschrittsverfolgung

SuperAgent wird beim Hoch- und Herunterladen großer Dateien ausgelöstFortschrittFall.

request.post(url) .attach('field_name', file) .on('progress', event => { /* Ereigniswert: { Richtung: "Upload" oder "Download" Prozent: 0 bis 100 // wenn unbekannt Dateigröße, möglicherweise nicht total: // Gesamtdateigröße, möglicherweise nicht geladen: // Anzahl der bisher heruntergeladenen oder hochgeladenen Bytes} */ }) .then()

Testen Sie auf localhost

Erzwingen Sie Verbindungen zu bestimmten IP-Adressen

In Node.js können Sie die DNS-Auflösung ignorieren und verwenden.verbinden()Die Methode leitet alle Anfragen an eine bestimmte IP-Adresse weiter. Diese Anfrage würde beispielsweise an „localhost“ gehenexample.com::

const res = waiting request.get("http://example.com").connect("127.0.0.1");

Da Anfragen möglicherweise umgeleitet werden, können mehrere Hostnamen und mehrere IPs sowie ein spezielles angegeben werden*Als Fallback (Hinweis: Es werden keine anderen Platzhalter unterstützt). Anfrage wird behaltenGastgeberDer ursprüngliche Wert des Anforderungsheaders.

const res = waiting request.get("http://redir.example.com:555") .connect({ "redir.example.com": "127.0.0.1", // redir.example.com:555 wird Verwenden Sie 127.0.0.1:555 „www.example.com“: false, // überschreiben Sie dies nicht; verwenden Sie DNS normalerweise „mapped.example.com“: { host: „127.0.0.1“, port: 8080}, / /mapped .example.com:* will use 127.0.0.1:8080 "*": "proxy.example.com", // alle anderen Anfragen werden an diesen Host gesendet});

Ignorieren Sie defektes/unsicheres HTTPS auf localhost

Wenn HTTPS in Node.js falsch konfiguriert und unsicher ist (z. B. die Verwendung eines selbstsignierten Zertifikats anstelle vonNicht angebenmein eigenes.ca()), ist ein Anruf weiterhin möglich.trustLocalhost()etwas erlaubenlocalhostAnfrage für:

const res = waiting request.get("https://localhost").trustLocalhost()

Und.connect("127.0.0.1")Zusammen kann dies dazu verwendet werden, HTTPS-Anfragen an jede beliebige Domäne zu erzwingen, zu der sie umgeleitet werdenlocalhost。

Es ist im Allgemeinen sicher, fehlerhaftes HTTPS auf localhost zu ignorieren, da die Loopback-Schnittstelle nicht für nicht vertrauenswürdige Netzwerke verfügbar ist. VertrauenlocalhostKönnte in Zukunft zur Standardeinstellung werden. verwenden.trustLocalhost(false)Obligatorische Inspektion127.0.0.1Zuverlässigkeit.

Wir unterstützen die Deaktivierung der HTTPS-Sicherheit bei Anfragen an andere IP-Adressen absichtlich nicht, da diese Optionen letztendlich als schnelle „Lösungen“ für HTTPS-Probleme missbraucht werden. Sie können von herunterladenLassen Sie uns verschlüsselnHolen Sie sich ein kostenloses HTTPS-Zertifikat oder richten Sie Ihre eigene CA ein (.as(as_public_pem)), um Ihr selbstsigniertes Zertifikat vertrauenswürdig zu machen.

Unterstützung von Promise- und Generatorfunktionen

Die Anfrage eines SuperAgents ist ein „thenable“-Objekt (ein Objekt mit einer then-Methode), das mit JavaScript Promise und kompatibel istasynchron/wartenGrammatisch kompatibel.

const res = Warten auf request.get(url);

Wenn Sie Promise verwenden,will nichtüberweisen.Ende()oder.Rohr(). jede Verwendung.Dann()odererwartenAlle anderen Möglichkeiten zur Verwendung von Anfragen sind deaktiviert. Bildcoso eine Bibliothek oder ähnlicheszuEin solcher Webframe kann auf jeder SuperAgent-Methode vorhanden seinErtrag::

const req = request .get('http://local') .auth('tobi', 'learnboost');const res = yield req;

Beachten Sie, dass SuperAgent eine globale erwartetVersprechenObjekt existiert. Sie benötigen eine Polyfüllung, um Promises in Internet Explorer oder Node.js 0.10 verwenden zu können.

Browser- und Knotenversion

Es gibt zwei Implementierungen von SuperAgent: eine für Webbrowser (mit XHR) und eine für Node.JS (mit dem Kern-http-Modul). Standardmäßig wählen Browserify und WebPack die Browserversion aus.

Wenn Sie Code für Node.JS mit WebPack kompilieren möchten, müssen Siemussin seiner Konfiguration angegebenKnotenziel。

Verwenden Sie die Browserversion in Electron

ElektronDie Entwickler berichten, dass Sie die Browserversion von SuperAgent anstelle der Node-Version verwenden könnenrequire('superagent/superagent'). Dadurch wird Ihre Anfrage auf der Registerkarte „Netzwerk“ der Chrome Developer Tools angezeigt. Beachten Sie, dass diese Umgebung weder von der automatisierten Testsuite abgedeckt noch offiziell unterstützt wird.

Verwenden Sie einen Proxy, um Anfragen zu senden

Kann die eines anderen Autors verwendenSuperagent-ProxyModul

Übersetzungsanweisungen

Der gesamte Inhalt des Dokuments wurde entsprechend dem englischen Originaldokument übersetzt und der Übersetzer ist nicht gut genug. Bitte weisen Sie daher auf Fehler hin