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

SuperAgent ist eine schlanke progressive Ajax-API, die auf Flexibilität, Lesbarkeit und eine geringe Lernkurve ausgelegt ist, nachdem sie mit vielen der vorhandenen Anforderungs-APIs frustriert war. 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)); });

Testdokumentation

Chinesisches Dokument

Die folgendeTestdokumentationwurde mit generiertMokkas„doc“-Reporter und spiegelt direkt die Testsuite wider. Dies stellt eine zusätzliche Dokumentationsquelle dar.

Grundlagen anfordern

Eine Anfrage kann durch Aufrufen der entsprechenden Methode initiiert werdenAnfrageObjekt, dann Aufruf.Dann()(oder.Ende() oder warten), um die Anfrage zu senden. Zum Beispiel ein einfachesERHALTENAnfrage:

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

Die HTTP-Methode kann auch als String übergeben werden:

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

Rückrufe im alten Stil werden ebenfalls unterstützt, aber nicht empfohlen.Anstatt .Dann()Du kannst anrufen.Ende():

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

Es können absolute URLs verwendet werden. In Webbrowsern funktionieren absolute URLs nur, wenn der Server sie implementiertCORS.

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

DerKnotenDer Kunde unterstützt das Stellen von Anfragen anUnix-Domänen-Sockets:

// Muster: https?+unix://SOCKET_PATH/REQUEST_PATH // „%2F“ als „/“ in SOCKET_PATH 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 }

LÖSCHEN,KOPF,PATCH,POST, UndSETZENAnfragen können ebenfalls verwendet werden, ändern Sie einfach den Methodennamen:

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

LÖSCHENkann auch als bezeichnet werden.des()für Kompatibilität mit altem IE wolöschenist ein reserviertes Wort.

Die HTTP-Methode ist standardmäßig aufERHALTEN, wenn Sie es also wünschen, gilt Folgendes:

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

Verwendung von HTTP/2

Um eine Anfrage nur über das HTTP/2-Protokoll (ohne HTTP/1.x-Fallback) zu stellen, verwenden Sie die.http2()Methode.

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

Header-Felder festlegen

Das Festlegen von Header-Feldern ist einfach: Aufrufen.Satz()mit einem Feldnamen und einem Wert:

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 einzigen Aufruf festzulegen:

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

ERHALTENAnfragen

Der.Anfrage()Die Methode akzeptiert Objekte, die bei Verwendung mit derERHALTENDie Methode bildet eine Abfragezeichenfolge. Im Folgenden wird der Pfad erstellt/search?query=Manny&range=1..5&order=desc.

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

Oder als einzelnes Objekt:

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

Der.Anfrage()Die Methode akzeptiert auch Zeichenfolgen:

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

Oder beigetreten:

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

KOPFAnfragen

Sie können auch die verwenden.Anfrage()Methode für HEAD-Anfragen. Im Folgenden wird der Pfad erstellt/users?email=joe@smith.com.

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

POST/SETZENAnfragen

Ein typisches JSONPOSTDie Anfrage könnte etwa wie folgt aussehen, wobei wir das Content-Type-Headerfeld entsprechend festlegen und einige Daten „schreiben“, in diesem Fall nur einen JSON-String.

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 es dasStandard! Das folgende Beispiel entspricht dem vorherigen.

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

Oder mehrere verwenden.schicken()Anrufe:

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

Standardmäßig wird das Senden von Zeichenfolgen festgelegtInhaltstypZuapplication/x-www-form-urlencoded, mehrere Anrufe werden mit verkettet&, hier resultierend inname=tj&pet=tobi:

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

SuperAgent-Formate sind erweiterbar, standardmäßig werden jedoch „json“ und „form“ unterstützt. Um die Daten zu senden alsapplication/x-www-form-urlencodedeinfach aufrufen.Typ()mit „form“, wobei der Standardwert „json“ ist. Diese Anfrage wirdPOSTder Körper „name=tj&pet=tobi“.

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

Senden einerFormulardatenObjekt wird ebenfalls unterstützt. Das folgende Beispiel wirdPOSTder Inhalt des durch id="myForm" identifizierten HTML-Formulars:

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

Einstellen derInhaltstyp

Die offensichtliche Lösung besteht darin, das zu verwenden.Satz()Methode:

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

Als Kurzschrift die.Typ()Die Methode ist ebenfalls verfügbar und akzeptiert den kanonisierten MIME-Typnamen komplett mit Typ/Subtyp oder einfach den Erweiterungsnamen wie „xml“, „json“, „png“ usw.:

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

Serialisieren des Anforderungstexts

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';};// Von nun an werden alle Anfragen mit einem Inhaltstyp von// 'application/xml' automatisch serialisiert

Wenn Sie die Nutzlast in einem benutzerdefinierten Format senden möchten, können Sie die integrierte Serialisierung durch ersetzen.serialize()Methode auf Anfragebasis:

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

Anfragen werden wiederholt

Wenn gegeben.wiederholen()Bei dieser Methode wiederholt SuperAgent automatisch Anfragen, wenn sie vorübergehend fehlschlagen oder auf eine fehlerhafte Internetverbindung zurückzuführen sein könnten.

Diese Methode verfügt über zwei optionale Argumente: Anzahl der Wiederholungsversuche (Standard 1) und einen Rückruf. Es ruftRückruf(err, res)vor jedem erneuten Versuch. Der Rückruf kann zurückkommenWAHR/FALSCHum zu steuern, ob die Anfrage wiederholt werden soll (es wird jedoch immer die maximale Anzahl von Wiederholungen angewendet).

request .get('https://example.com/search') .retry(2) // oder: .retry(2, callback) .then(finished); .catch(fehlgeschlagen);

Verwenden.wiederholen()nur mit Anfragen, die es sindidempotent(d. h. mehrere Anfragen, die den Server erreichen, verursachen keine unerwünschten Nebenwirkungen wie Doppelkäufe).

Alle Anforderungsmethoden werden standardmäßig ausprobiert (das heißt, wenn Sie nicht möchten, dass POST-Anfragen erneut versucht werden, müssen Sie einen benutzerdefinierten Wiederholungsrückruf übergeben).

Standardmäßig werden die folgenden Statuscodes wiederholt:

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

Standardmäßig werden die folgenden Fehlercodes wiederholt:

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

Akzeptieren einstellen

In ähnlicher Weise wie die.Typ()Methode ist es auch möglich, die festzulegenAkzeptierenHeader über die Kurzschriftmethode.akzeptieren(). Welche Referenzenrequest.typesAußerdem können Sie entweder den vollständigen kanonisierten MIME-Typnamen angeben alsTyp/Subtypoder der Einfachheit halber die Erweiterungssuffixform „xml“, „json“, „png“ usw.:

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 eineAkzeptieren: application/jsonHeader in Ihrer Anfrage. Wenn Sie dies nicht tun, antwortet Facebook mitInhaltstyp: Text/Javascript; Zeichensatz=UTF-8, die SuperAgent nicht analysiert und daherres.körperwird undefiniert sein. Sie können dies mit beiden tunreq.accept('json')oderreq.set('Accept', 'application/json'). SehenHeft 1078für Details.

Abfragezeichenfolgen

req.query(obj)ist eine Methode, die zum Aufbau einer Abfragezeichenfolge verwendet werden kann. Zum Beispiel bevölkern?format=json&dest=/loginauf einenPOST:

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

Standardmäßig wird die Abfragezeichenfolge nicht in einer bestimmten Reihenfolge zusammengestellt. Eine asziibisch sortierte Abfragezeichenfolge kann mit aktiviert werdenreq.sortQuery(). Sie können auch eine benutzerdefinierte Sortiervergleichsfunktion bereitstellenreq.sortQuery(myComparisonFn). Die Vergleichsfunktion sollte zwei Argumente annehmen und eine negative/null/positive Ganzzahl zurückgeben.

// Standardreihenfolge request.get('/user') .query('name=Nick') .query('search=Manny') .sortQuery() .then(callback) // angepasste 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/die CA-Zertifikat(e) auf vertrauenswürdig ein
• .cert(): Legen Sie die Client-Zertifikatskette(n) fest.
• .Taste(): Legen Sie die privaten Schlüssel des Clients fest.
• .pfx(): Legen Sie den PFX- oder PKCS12-codierten privaten Schlüssel und die Zertifikatskette des Clients fest
• .disableTLSCerts(): Abgelaufene oder ungültige TLS-Zertifikate werden nicht abgelehnt. Wird intern festgelegtRejectUnauthorized=true.Seien Sie gewarnt, diese Methode ermöglicht MITM-Angriffe.

Weitere Informationen finden Sie unter Node.jshttps.Dokumente anfordern.

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 => {});

Antworttexte analysieren

SuperAgent analysiert für Sie bekannte Antworttextdaten und unterstützt derzeitapplication/x-www-form-urlencoded,application/json, UndMultipart-/Formulardaten. Sie können die automatische Analyse auch für andere Antworttextdaten einrichten:

//browserrequest.parse['application/xml'] = function (str) { return {'object': 'parsed from str'};};//noderequest.parse['application/xml'] = function (res, cb) { //Antworttext analysieren und res.body hier setzen cb(null, res);};//In Zukunft werden Antworten vom Typ „application/xml“//automatisch analysiert

Sie können einen benutzerdefinierten Parser festlegen (der Vorrang vor integrierten Parsern hat)..buffer(true).parse(fn)Methode. Wenn die Antwortpufferung nicht aktiviert ist (.buffer(false)) dann ist dieAntwortDas Ereignis wird ausgegeben, ohne auf den Abschluss des Body-Parsers zu wartenAntwortkörperwird nicht verfügbar sein.

JSON / Urlencodiert

Die Eigenschaftres.körperist das analysierte Objekt, beispielsweise wenn eine Anfrage mit der JSON-Zeichenfolge „{“user“:{“name“: „tobi“}}“ geantwortet hat,res.body.user.namewäre „tobi“. Ebenso würde der x-www-form-urlencoded-Wert von „user[name]=tobi“ das gleiche Ergebnis liefern. Es wird nur eine Verschachtelungsebene unterstützt. Wenn Sie komplexere Daten benötigen, senden Sie stattdessen JSON.

Arrays werden durch Wiederholen des Schlüssels gesendet..send({color: ['red','blue']})sendetFarbe=Rot&Farbe=Blau. Wenn Sie möchten, dass die Array-Schlüssel Folgendes enthalten:[]in ihrem Namen müssen Sie es selbst hinzufügen, da SuperAgent es nicht automatisch hinzufügt.

Mehrteilig

Der Node-Client unterstütztMultipart-/Formulardatenüber dieBeeindruckendModul. Beim Parsen mehrteiliger Antworten das Objektres.filessteht Ihnen ebenfalls zur Verfügung. Angenommen, eine Anfrage antwortet beispielsweise mit dem folgenden mehrteiligen Text:

--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--

Du hättest die Werteres.body.namebereitgestellt als „Tobi“, undres.files.imageAls einDateiObjekt, das den Pfad auf der Festplatte, den Dateinamen und andere Eigenschaften enthält.

Binär

In Browsern 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 Argumentwerte für diese Methode sind:

• 'Klecks'wird an die XmlHTTPRequest weitergeleitetAntworttypEigentum
• 'Arraybuffer'wird an die XmlHTTPRequest weitergeleitetAntworttypEigentum

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

Weitere Informationen finden Sie im Mozilla Developer Networkxhr.responseType-Dokumente.

Antworteigenschaften

Auf der Seite sind viele hilfreiche Flags und Eigenschaften festgelegtAntwortObjekt, das vom Antworttext, dem analysierten Antworttext, Headerfeldern, Statusflags und mehr reicht.

Antworttext

Derres.textDie Eigenschaft enthält die ungeparste Antworttextzeichenfolge. Diese Eigenschaft ist für die Client-API immer vorhanden und nur, wenn der MIME-Typ mit „text/“ übereinstimmt.","/json“ oder standardmäßig „x-www-form-urlencoded“ für den Knoten. Der Grund dafür ist, Speicher zu sparen, da das Puffern von Text aus großen Textkörpern wie mehrteiligen Dateien oder Bildern äußerst ineffizient ist. Informationen zum Erzwingen der Pufferung finden Sie unter „Antworten puffern“. " Abschnitt.

Antwortkörper

So wie SuperAgent Anforderungsdaten automatisch serialisieren kann, kann er diese auch automatisch analysieren. Wenn ein Parser für den Content-Type definiert wird, wird dieser analysiert, was standardmäßig „application/json“ und „application/x-www-form-urlencoded“ umfasst. Das geparste Objekt ist dann über verfügbarres.körper.

Antwort-Header-Felder

Derres.headerenthält ein Objekt aus geparsten Header-Feldern, Feldnamen in Kleinbuchstaben, ähnlich wie bei Node. Zum Beispielres.header['content-length'].

Inhaltstyp der Antwort

Der Content-Type-Antwortheader ist in Sonderfällen angegebenres.typ, in dem der Zeichensatz (falls vorhanden) fehlt. Beispielsweise liefert der Inhaltstyp „text/html; charset=utf8“ „text/html“ alsres.typ, und dasres.charsetDie Eigenschaft würde dann „utf8“ enthalten.

Antwortstatus

Die Antwortstatus-Flags helfen neben anderen nützlichen Informationen dabei, festzustellen, ob die Anfrage erfolgreich war, wodurch sich SuperAgent ideal für die Interaktion mit RESTful-Webdiensten eignet. 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; // Zucker 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;

Anfragen werden abgebrochen

Um Anfragen abzubrechen, rufen Sie einfach die aufreq.abort()Methode.

Auszeiten

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

• req.timeout({deadline:ms})oderreq.timeout(ms)(WoMSist eine Anzahl von 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 Zeit, die der gesamte Download dauern kann. Das Antwort-Timeout sollte mindestens einige Sekunden länger sein als nur die Zeit, die der Server zum Antworten benötigt, da es auch die Zeit für die DNS-Suche, TCP/IP- und TLS-Verbindungen sowie die Zeit für das Hochladen von Anforderungsdaten umfasst.

Sie sollten beide verwendenTerminUndAntwortAuszeiten. Auf diese Weise können Sie eine kurze Reaktionszeit nutzen, um nicht reagierende Netzwerke schnell zu erkennen, und eine lange Frist nutzen, um Zeit für Downloads in langsamen, aber zuverlässigen Netzwerken zu geben. Beachten Sie, dass beide Timer die Dauer begrenzenUploadsder angehängten Dateien dürfen übernommen werden. Verwenden Sie lange Zeitüberschreitungen, wenn Sie Dateien hochladen.

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 fertig ist wird geladen. }) .then(res => { /* rechtzeitig geantwortet */ }, err => { if (err.timeout) { /* Zeitüberschreitung! */ } else { /* anderer Fehler */ } }) ;

Timeout-Fehler haben eine.AuszeitEigentum.

Authentifizierung

Sowohl im Knoten als auch im Browser ist die Authentifizierung über verfügbar.auth()Methode:

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

ImKnotenDie Client-Basisauthentifizierung kann in der URL als „user:pass“ enthalten sein:

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

Nur standardmäßigBasicAuthentifizierung wird verwendet. Im 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'})

DerAutorMethode unterstützt auch aTypvonTräger, um die tokenbasierte Authentifizierung anzugeben:

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

Weiterleitungen folgen

Standardmäßig werden bis zu 5 Weiterleitungen verfolgt, Sie können dies jedoch mit festlegenres.redirects(n)Methode:

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

Weiterleitungen, die das Limit überschreiten, werden als Fehler behandelt. Verwenden.ok(res => res.status < 400)um sie als erfolgreiche Antworten zu lesen.

Agenten für den globalen Staat

Cookies speichern

In Node speichert SuperAgent standardmäßig keine Cookies, Sie können jedoch die verwenden.Agent()Methode zum Erstellen einer Kopie von SuperAgent, die Cookies speichert. Jede Kopie hat eine separate Keksdose.

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

In Browsern werden Cookies automatisch vom Browser verwaltet, sodass die.Agent()isoliert keine Cookies.

Standardoptionen für mehrere Anfragen

Auf dem Agent aufgerufene reguläre Anforderungsmethoden werden als Standard für alle von diesem Agent gestellten Anforderungen verwendet.

const agent = request.agent() .use(plugin) .auth(shared); Warten Sie auf agent.get('/with-plugin-and-auth'); wait agent.get('/also-with-plugin-and-auth');

Die vollständige Liste der Methoden, die der Agent 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.

Rohrleitungsdaten

Mit dem Node-Client können Sie Daten an und von der Anfrage weiterleiten. Bitte beachte, dass.Rohr()wird eingesetztanstatt .Ende()/.Dann()Methoden.

Beispiel: Den Inhalt einer Datei als Anfrage weiterleiten:

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 Superagent die weitergeleiteten Daten mit sendet, wenn Sie eine Anfrage weiterleitenChunked-Transfer-Kodierung, was nicht von allen Servern unterstützt wird (z. B. Python-WSGI-Server).

Oder die Antwort an eine Datei weiterleiten:

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

Es ist nicht möglich, Anspielungen und Rückrufe oder Versprechen zu vermischen. Beachten Sie, dass Sie dies tun solltenNICHTVersuchen Sie, das Ergebnis von weiterzuleiten.Ende()oder derAntwortObjekt:

// Tun Sie nichts davon: const stream = getAWritableStream(); const req = request .get('/some.json') // SCHLECHT: Dies leitet Müll an 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() // SCHLECHT: Dies wird auch nicht unterstützt, .pipe ruft .end für Sie auf. .pipe(nope_its_too_late);

In einemzukünftige Versionvon Superagent, unzulässige Anrufe anRohr()wird versagen.

Mehrteilige Anfragen

SuperAgent eignet sich auch hervorragend fürGebäudemehrteilige Anfragen, für die es Methoden bereitstellt.anfügen()Und.Feld().

Wenn Sie verwenden.Feld()oder.anfügen()Du kannst es nicht verwenden.schicken()Und dudarf nichtSatzInhaltstyp(Der richtige Typ wird für Sie eingestellt).

Anhängen von Dateien

Um eine Datei zu senden, verwenden Sie.attach(Name, [Datei], [Optionen]). Sie können durch einen Anruf mehrere Dateien anhängen.anfügenmehrmals. Die Argumente sind:

• Name— Feldname im Formular.
• Datei— entweder String mit Dateipfad oderKlecks/PufferObjekt.
• Optionen– (optional) entweder Zeichenfolge mit benutzerdefiniertem Dateinamen oder{Dateiname: Zeichenfolge}Objekt. Auch im Node{contentType: 'mime/type'}wird unterstützt. Erstellen Sie im Browser eineKlecksstattdessen mit einem entsprechenden Typ.

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

Feldwerte

Ähnlich wie bei Formularfeldern in HTML können Sie mit Feldwerte festlegen.field(Name, Wert)Und.field({name: value}). Angenommen, Sie möchten ein paar Bilder mit Ihrem Namen und Ihrer E-Mail-Adresse hochladen. Ihre Anfrage könnte etwa 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, das Beste ist: Sie müssen nichts tun! Es funktioniert einfach.

Antworten puffern

Um die Pufferung von Antwortkörpern zu erzwingenres.textSie können sich berufenreq.buffer(). Um die Standardpufferung für Textantworten wie „text/plain“, „text/html“ usw. rückgängig zu machen, können Sie Folgendes aufrufen:req.buffer(false).

Bei der Pufferung derres.gepuffertWenn das Flag bereitgestellt wird, können Sie damit 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 stimmt der Verwendung von CORS-Headern zu. Browser machen auch extraOPTIONENAnfragen, um zu überprüfen, welche HTTP-Header und -Methoden vom Server zugelassen werden.Lesen Sie mehr über CORS.

Der.withCredentials()Die Methode ermöglicht das Senden von Cookies vom Ursprungsort, jedoch nur dann, wennZugriffskontrolle-Zulassen-UrsprungIstnichtein Platzhalter („*“) undZugangskontrolle-Zulassen-Anmeldeinformationenist 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 Argumente übergeben: Fehler und Antwort. Wenn kein Fehler aufgetreten ist, ist das erste Argument null:

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

Außerdem wird ein „Fehler“-Ereignis ausgegeben, mit dem Sie Folgendes abwarten können:

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

Beachten Sie, dassSuperagent berücksichtigt standardmäßig 4xx- und 5xx-Antworten (sowie nicht behandelte 3xx-Antworten).. Wenn Sie beispielsweise eine erhalten304 Nicht geändert,403 Verbotenoder500 Interner ServerfehlerAntwort, diese Statusinformationen werden über verfügbar seinFehlerstatus. Fehler aus solchen Antworten enthalten auch eineFehlerantwortFeld mit allen in „Antworteigenschaften". Die Bibliothek verhält sich auf diese Weise, um den häufigen Fall zu bewältigen, dass Erfolgsantworten gewünscht werden und HTTP-Fehlerstatuscodes als Fehler behandelt werden, während gleichzeitig eine benutzerdefinierte Logik für bestimmte Fehlerbedingungen möglich ist.

Netzwerkausfälle, Zeitüberschreitungen und andere Fehler, die keine Antwort hervorrufen, enthalten „Nein“.FehlerstatusoderFehlerantwortFelder.

Wenn Sie 404- oder andere HTTP-Fehlerantworten verarbeiten möchten, können Sie dies abfragenFehlerstatusEigentum. Wenn ein HTTP-Fehler auftritt (4xx- oder 5xx-Antwort), wird derRes.FehlerEigentum ist einFehlerObjekt können Sie auf diese Weise Prüfungen durchführen wie:

if (err && err.status === 404) { Alert('oh no ' + res.body.message); } else if (err) { // alle anderen Fehlertypen, die wir generisch behandeln }

Alternativ können Sie die verwenden.ok(Rückruf)Methode, um zu entscheiden, ob eine Antwort ein Fehler ist oder nicht. Der Rückruf zumOKDie Funktion erhält eine Antwort und kehrt zurückWAHRob die Antwort als Erfolg gewertet werden soll.

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

Fortschrittsverfolgung

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

request.post(url) .attach('field_name', file) .on('progress', event => { /* das Ereignis ist: { Richtung: "upload" oder "download" Prozent: 0 bis 100 // kann fehlen, wenn die Dateigröße unbekannt ist total: // Gesamtdateigröße, kann fehlen geladen: // Bisher heruntergeladene oder hochgeladene Bytes } */ }) .then()

Testen auf localhost

Erzwingen einer bestimmten Verbindungs-IP-Adresse

In Node.js ist es möglich, die DNS-Auflösung zu ignorieren und alle Anfragen an eine bestimmte IP-Adresse weiterzuleiten.verbinden()Methode. Diese Anfrage geht beispielsweise an localhost stattexample.com:

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

Da die Anfrage möglicherweise umgeleitet wird, ist es möglich, mehrere Hostnamen und mehrere IPs sowie eine spezielle Angabe anzugeben*als Fallback (Hinweis: Andere Platzhalter werden nicht unterstützt). Die Anfragen bleiben erhaltenGastgeberHeader mit dem ursprünglichen Wert..connect(undefiniert)schaltet die Funktion aus.

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

Defektes/unsicheres HTTPS auf localhost wird ignoriert

In Node.js, wenn HTTPS falsch konfiguriert und unsicher ist (z. B. Verwendung eines selbstsignierten Zertifikats).ohneEigene angeben.ca()), ist es weiterhin möglich, Anfragen zuzulassenlocalhostper Anruf.trustLocalhost():

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

Zusammen mit.connect("127.0.0.1")Dies kann verwendet werden, um HTTPS-Anfragen an eine beliebige Domäne zu erzwingen, zu der sie umgeleitet werdenlocalhoststattdessen.

Im Allgemeinen ist es sicher, defektes HTTPS zu ignorierenlocalhost, da die Loopback-Schnittstelle nicht für nicht vertrauenswürdige Netzwerke verfügbar ist. Vertrauensvolllocalhostkönnte in Zukunft zum Standard werden. Verwenden.trustLocalhost(false)Überprüfung erzwingen127.0.0.1Authentizität.

Wir unterstützen die Deaktivierung der HTTPS-Sicherheit bei Anfragen an andere IP-Adressen absichtlich nicht, da solche Optionen letztendlich als schnelle „Lösung“ für HTTPS-Probleme missbraucht werden. Sie können kostenlose HTTPS-Zertifikate von erhaltenLassen Sie uns verschlüsselnoder legen Sie Ihre eigene CA fest (.as(as_public_pem)), um Ihre selbstsignierten Zertifikate vertrauenswürdig zu machen.

Promise- und Generator-Unterstützung

Die Anfrage von SuperAgent ist ein „thenable“-Objekt, das mit JavaScript-Versprechungen und dem kompatibel istasynchron/erwartenSyntax.

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

Wenn Sie Versprechen verwenden,unterlassen SieForderung.Ende()oder.Rohr(). Jede Verwendung von.Dann()odererwartendeaktiviert alle anderen Möglichkeiten zur Verwendung der Anfrage.

Bibliotheken mögencooder ein Webframework wiezudürfenErtragauf jeder SuperAgent-Methode:

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

Beachten Sie, dass SuperAgent das globale erwartetVersprechenObjekt vorhanden sein. Sie müssen Version 7 und eine Polyfüllung verwenden, um Versprechen in Internet Explorer oder Node.js 0.10 verwenden zu können.

Wir haben die Unterstützung für IE in Version 8 eingestellt. Sie müssen ein Polyfill für WeakRef und BigInt hinzufügen, wenn Sie beispielsweise Opera 85, iOS Safari 12.2-12.5 unterstützen möchtenhttps://polyfill.io:

Browser- und Knotenversionen

SuperAgent verfügt über zwei Implementierungen: 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 WebPack zum Kompilieren von Code für Node.JS verwenden möchten, müssen Sie Folgendes tunmussangebenKnotenzielin seiner Konfiguration.