Erste Schritte mit dem Usage Service und den APIs

Dieser Artikel zeigt, wie Sie einen einfachen Server einrichten, um Usage-Service-Ereignisse (einen Echo-Server) zu sammeln und auf der Konsole anzuzeigen. Sie lernen auch, wie Sie ein Beispiel-API-Projekt aufbauen, das Ereignisse an den Echo-Server sendet. Außerdem erfahren Sie, wie Sie das an den Usage Service gesendete Ereignis mithilfe von Umgebungsvariablen ändern können.

Voraussetzungen

Sie müssen Node.js installieren, um dieses Beispiel verwenden zu können. Siehe Node.js für das Node.js-Installationsprogramm.

Einrichtung eines Echo-Servers

Erstellen Sie eine Datei mit dem unten gezeigten Code:

const express = require('express')
const bodyParser = require('body-parser')

const app = express()

// Parse JSON bodies.
app.use(bodyParser.json())
// Accept events.
app.post('/:version/event', (req, res) => {
  const event = req.body
  console.log(event)

  // Respond so the client is happy.
  res.status(200)
  res.send('Event accepted!')
})

// Listen for requests.
app.listen(3000)

Wir nennen die Datei echo-server.js. Speichern Sie sie in einem neuen Verzeichnis und wechseln Sie in dieses Verzeichnis.

Der Server hört auf Port 3000 auf Anfragen und schreibt den empfangenen Anfragetext in die Konsole. Jedes Mal, wenn ein API-Client oder ein CLI-Test ausgeführt wird (und die Nutzungsprotokollierung aktiviert ist), schreibt der Echo-Server das empfangene Nutzungsevent.

Installieren Sie express und body-parser, zwei Abhängigkeiten, die zum Ausführen des obigen Codes erforderlich sind:

npm i express body-parser

Starten Sie den Echo-Server:

node echo-server.js

Erstellen eines Tests

Sie können den Beispiele-Katalog verwenden, um Beispieltestcode zu erhalten. Wenn Sie den Testcode ausführen, sendet er Nutzungsmetriken an den Echo-Server, den Sie im vorherigen Abschnitt erstellt haben.

Starten Sie ein neues Terminal- oder Konsolenfenster für die folgenden Schritte.

Klonen Sie das Deque-Examples-Katalog-Repository auf GitHub und wechseln Sie dann in dieses Verzeichnis:

git clone git@github.com:dequelabs/axe-devtools-html-api-examples.git
cd axe-devtools-html-api-examples

Für dieses Beispiel haben wir das Node.js Playwright-Codebeispiel verwendet. Wechseln Sie in dieses Verzeichnis und installieren Sie die erforderlichen Node.js-Pakete:

cd Node/playwright
npm i

Möglicherweise müssen Sie auch die Abhängigkeiten von Playwright installieren:

npx playwright install

Setzen Sie nun die erforderlichen Umgebungsvariablen, um die Metrikberichterstattung zu aktivieren, und setzen Sie den Server auf den lokalen Echo-Server, den Sie zuvor erstellt haben:

• export AXE_TRACK_USAGE=true
• export AXE_METRICS_URL=http://localhost:3000

Sie können die Umgebungsvariablen festlegen und die Tests (npm test) über die Befehlszeile unter Linux und macOS ausführen:

AXE_TRACK_USAGE=true AXE_METRICS_URL=http://localhost:3000 npm test

set AXE_TRACK_USAGE=true
set AXE_METRICS_URL=http://localhost:3000

setx AXE_TRACK_USAGE true
setx AXE_METRICS_URL http://localhost:3000

Das Terminalfenster, das den laufenden Echo-Server enthält, zeigt Ergebnisse wie die folgenden:

{
  dateTime: '2023-01-20T17:26:54.371Z',
  productComponent: 'api-node-playwright',
  productName: 'axe-devtools-html',
  version: 'v2',
  event: 'analyze',
  distinctId: '1b8a5e67-eb1f-4637-9668-be3a332d2c41',
  applicationProperties: {
    target: 'https://broken-workshop.dequelabs.com/',
    target_medium: 'text/html',
    engineVersion: '4.5.2',
    failedRuleCount: 2,
    failedRuleNames: 'color-contrast,label',
    failedItemCount: 5,
    inapplicableRuleCount: 39,
    incompleteRuleCount: 2,
    passedRuleCount: 21,
    testResults: {}
  }
}

Details zu den Eigenschaften dieses Objekts finden Sie unter Das Ereignisobjekt.

Ändern des Ereignisses mithilfe von Umgebungsvariablen

Sie können das Ereignis, das die APIs oder die CLI an den Usage Service senden, mit Umgebungsvariablen ändern. Dieses Beispiel zeigt, wie man das Ereignis ändert.

Zuerst setzen Sie eine Umgebungsvariable für den Wert, den Sie ändern möchten, zum Beispiel:

export AXE_DEPARTMENT="test department"

Dies wird die department-Eigenschaft des Ereignisobjekts ändern, wie das unten stehende Beispiel zeigt (unter Linux oder macOS):

AXE_DEPARTMENT="test department" AXE_TRACK_USAGE=true AXE_METRICS_URL=http://localhost:3000  npm test

Im Terminalfenster, in dem der Echo-Server ausgeführt wird, sollten Sie ein Ereignis sehen, das department-Informationen enthält, wie die unten hervorgehobene Zeile zeigt:

{
  dateTime: '2023-01-20T17:31:48.422Z',
  productComponent: 'api-node-playwright',
  productName: 'axe-devtools-html',
  version: 'v2',
  event: 'analyze',
  distinctId: '18cd1262-b5b7-4681-9f7a-a7d4c97745c8',
  applicationProperties: {
    target: 'https://broken-workshop.dequelabs.com/',
    target_medium: 'text/html',
    engineVersion: '4.5.2',
    failedRuleCount: 2,
    failedRuleNames: 'color-contrast,label',
    failedItemCount: 5,
    inapplicableRuleCount: 39,
    incompleteRuleCount: 2,
    passedRuleCount: 21,
    testResults: {}
  },
  department: 'test department'}

Weitere Informationen zu den Umgebungsvariablen, die Sie verwenden können, um Nutzungsereignisse zu ändern, finden Sie unter Steuerung des Usage Service über Umgebungsvariablen.

Nächste Schritte

Um einer Version dieses Tutorials für die CLI zu folgen, siehe Erste Schritte mit dem Usage Service und der CLI.

Für Übersichtsinformationen zum Usage Service siehe Der Usage Service.

Für eine Referenz des Ereignisobjekts siehe Referenz der Ereignisse des Usage Service.