Ergebnisse programmgesteuert abrufen

Umstellung auf die Sessions- und Ergebnis-API

Der neue Sessions- und Ergebnis-API ersetzt diesen Endpunkt durch zwei separate Endpunkte: einen, um Sitzungen für ein Projekt aufzulisten, und einen, um Ergebnisse für eine bestimmte Sitzung abzurufen. Dieses Zwei-Schritt-Modell gibt Ihnen Zugang zu allen Sitzungen über Zweige und Commits hinweg, nicht nur zur neuesten.

Äquivalente Anfrage mit format=summary

Der format=summary-Modus des Ergebnisendpunkts gibt die gleiche JSON-Struktur zurück wie dieser Endpunkt. Um eine bestehende Anfrage zu replizieren, finden Sie zunächst die Sitzung, die Ihrem Zweig oder Commit entspricht, und fordern dann deren Ergebnisse an:

1. Sitzungen auflisten, um die session_id für den Zweig oder Commit zu finden, der für Sie von Interesse ist, unter Verwendung der git_branch- oder commit_sha-Filter:

   curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
     "https://axe.deque.com/api-pub/v1/results/projects/$PROJECT_ID/sessions?git_branch=$GIT_BRANCH"

2. Ergebnisse anfordern für diese Sitzung durch session_id, unter Verwendung von format=summary für die gleiche JSON-Struktur wie dieser Endpunkt:

   curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
     "https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results?format=summary"

   important

   Der neue Endpunkt gibt 204 No Content zurück, während Ergebnisse generiert werden, genauso nicht 202 Processing wie dieser Endpunkt. Wenn Sie vorhandenen Code haben, der auf eine 202-Antwort wartet, aktualisieren Sie ihn, um stattdessen 204 zu verarbeiten. Siehe Sitzungsstatus und das Polling-Muster für ein vollständiges Polling-Beispiel.

Weiter mit format=full

Wenn Sie die vollständigen Details auf Problembene über das hinaus, was die Zusammenfassung bietet, erhalten möchten, verwenden Sie format=full, um Ergebnisse in Universelles JSON (gemeinsames Exportformat) abzurufen. Dieses Format umfasst jedes während der Sitzung gefundene Barrierefreiheitsproblem: individuelle Verstöße, unvollständige Überprüfungen, bestandene Prüfungen und nicht anwendbare Regeln, organisiert nach Seiten.

curl -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
  "https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results?format=full"

Referenz für den veralteten Endpunkt

Der herunterladbare Berichte REST-Service ermöglicht es Ihnen, eine Zusammenfassung Ihrer Barrierefreiheitsergebnisse des Axe Developer Hub als JSON-Daten herunterzuladen, um sie weiter zu verarbeiten oder in andere Software zu importieren. Der GET-Service hat zwei erforderliche Parameter:

• API-Schlüssel - Finden Sie einen persönlichen API-Schlüssel, der zu Ihrem Projekt passt, oder fügen Sie einen neuen API-Schlüssel im Axe-Konto-Portal hinzu. Wählen Sie einen API-Schlüssel des Axe Developer Hub, wenn Ihr Projekt die Web-APIs, CLI oder Watcher verwendet. Verwenden Sie einen Axe DevTools Mobile API-Schlüssel für mobile Projekte.
• Projekt-ID - Geben Sie die Projekt-ID für die entsprechenden Projektdaten an, die Sie herunterladen möchten. Finden Sie Ihre Projekt-ID in Axe Developer Hub.

Sie können zwei optionale Parameter verwenden, um Ihre Abfrage auf einen bestimmten Git-Zweig oder einen bestimmten Git-Commit-SHA zu begrenzen.

Anfragezusammenfassung

• Endpunkt: https://axe.deque.com/api-pub/watcher/downloadable/report
• Anfrage: GET
• Headers (erforderlich):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Abfrageparameter:
  • project_id (Erforderlich)
    • Beschreibung: Gibt die Projekt-ID für das Projekt an, dessen Bericht Sie herunterladen möchten. Dieser Parameter ist erforderlich.
    • Beispielnutzung: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
  • branch_name (Optional)
    • Beschreibung: Gibt den herunterladbaren Bericht für den angegebenen Git-Zweignamen zurück.
    • Beispielnutzung: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&branch_name=<GIT_BRANCH>
  • commit_sha (Optional)
    • Beschreibung: Gibt den herunterladbaren Bericht für den angegebenen Git-Commit-SHA zurück.
    • Beispielnutzung: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Beispiel curl-Anfrage

curl -L -H 'Accept: application/json' -H 'X-API-Key: <DEQUE_API_KEY>' 'https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>'

Beispiel Antwortkörper

{
  "report_id": "a4990926-3014-4799-aa39-7aca31fce412",
  "source": {
    "product_name": "axe-devtools-html",
    "product_component_name": "axe-devtools-watcher",
    "product_version": "3.20.2"
  },
  "test_details": {
    "test_id": "da0c79a5-6f1e-4692-a255-5757629208fa",
    "start_date": "2025-05-05T20:02:31.883Z",
    "end_date": "2025-05-05T20:02:42.789Z"
  },
  "commit": {
    "sha": "f73ea5a02386b359ffa79a76473f7a5ad41759d5",
    "author": "John Doe",
    "author_email": "john.doe@example.com",
    "message": "Merge pull request #233 from deque/221-add-examples-for-using-global-config-fields-2",
    "branch_name": "main",
    "repository_url": "https://github.com/dequelabs/watcher-examples.git",
    "tag": null
  },
  "devhub_summary": {
    "issue_count_total": 17,
    "issue_count_by_impact": {
      "critical": 0,
      "serious": 2,
      "moderate": 15,
      "minor": 0
    },
    "issue_count_by_rule": [
      {
        "severity": "serious",
        "rule_id": "color-contrast",
        "rule_help": "Elements must meet minimum color contrast ratio thresholds",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/color-contrast?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "heading-order",
        "rule_help": "Heading levels should only increase by one",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/heading-order?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "landmark-one-main",
        "rule_help": "Document should have one main landmark",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/landmark-one-main?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "page-has-heading-one",
        "rule_help": "Page should contain a level-one heading",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/page-has-heading-one?application=axeAPI",
        "count": 2
      },
      {
        "severity": "moderate",
        "rule_id": "region",
        "rule_help": "All page content should be contained by landmarks",
        "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/region?application=axeAPI",
        "count": 9
      }
    ]
  }
}

Antwortobjekt

Die folgenden Abschnitte beschreiben die JSON-Objekte im Antwortkörper.

Struktur der obersten Ebene

sourceObjekt

Enthält Informationen über das Produkt, das den Bericht erstellt hat:

test_detailsObjekt

Enthält Informationen über die Testausführung:

commitObjekt

Enthält Informationen über den mit dem Test verknüpften Git-Commit:

devhub_summaryObjekt

Enthält zusammenfassende Informationen über gefundene Barrierefreiheitsprobleme:

issue_count_by_impactObjekt

Gliedert die Probleme nach Auswirkungsgrad auf:

issue_count_by_ruleArray

Jedes Objekt in diesem Array repräsentiert eine Regel mit folgender Struktur:

Zusätzliche Antworten

202 Processing

Diese Antwort zeigt an, dass der Bericht noch erstellt wird, und Sie müssen Ihre Anfrage nach einer Wartezeit erneut versuchen.

Antwortkörper

{
  "message": "Report is still processing",
  "state": "PROCESSING"
}

429 Too Many Requests

In Zeiten hoher Auslastung kann dieser Endpunkt mit 429 Too Many Requests antworten, anstatt die Verarbeitung sofort zu starten. Die zugrunde liegende Arbeit bleibt in der Warteschlange, sodass erneute Versuche keine doppelte Verarbeitung verursachen. Die Antwort enthält einen Retry-After-Header, in Sekunden — warten Sie mindestens so lange, bevor Sie es erneut versuchen.

Antwortkörper

{
  "error": "Too many requests. Retry after the Retry-After interval."
}

400 Bad Request

Der für commit_sha angegebene Wert ist kein SHA-1-Wert.

Antwortkörper

{
  "error": "commit_sha must be a valid SHA-1 hash"
}

401 Unauthorized

Eine der folgenden Fehlermeldungen wird die 401 Unauthorized-Antwort begleiten.

Der angegebene API-Schlüssel ist nicht gültig

Antwortkörper

{
  "error": "Invalid API key"
}

Es gibt keinen erforderlichen Header mit einem API-Schlüssel:

Antwortkörper

{
  "error": "X-API-Key or Authorization header required"
}

404 Not Found

Eine der folgenden Fehlermeldungen wird die 404 Not Found-Antwort begleiten.

Der mit commit_shaverwendete SHA-Wert konnte nicht gefunden werden

Dieser Fehler zeigt an, dass es keine Daten zu diesem SHA im Axe Developer Hub gibt, was normalerweise bedeutet, dass die Testsuite nicht gegen diesen Git-Commit ausgeführt wurde. Beachten Sie, dass dies derselbe Fehler ist, der bei einem Zweignamen zurückgegeben wird, der nicht existiert. (Siehe den nächsten Fehler.)

Antwortkörper

{
  "error": "Session not found"
}

Der angegebene Wert für branch_nameexistiert nicht

Diese Fehlerantwort ist dieselbe wie der vorherige Fehler (wenn der mit dem commit_sha-Abfrageparameter angegebene SHA nicht in den Daten des Axe Developer Hub existiert).

Antwortkörper

{
  "error": "Session not found"
}

Der angegebene Wert für project_idexistiert nicht

Diese Fehlerantwort ist dieselbe wie die vorherigen 404-Fehler.

Antwortkörper

{
  "error": "Session not found"
}

Umgang mit einer 202 Processing-Antwort

Dieses Demonstrations-Shell-Skript zeigt, wie curl verwendet wird, um Ihren Bericht erneut anzufordern, wenn Sie eine 202 Processing-Antwort erhalten. Da Test-Suites zahlreiche Zugriffsverletzungen finden können, benötigt unser System möglicherweise zusätzliche Zeit, um alle Ergebnisse zu verarbeiten, bevor der Bericht zum Download bereitsteht. Wir empfehlen, das untenstehende Beispiel zu verwenden, um ein Skript zu erstellen, das kontinuierlich neu versucht und überprüft, ob die Ergebnisse bereits verfügbar sind. Es wird die Anfrage bis zu 20 Mal wiederholen, mit einer fünfsekündigen Verzögerung zwischen den Versuchen.

Das Beispiel erfordert, dass die Umgebungsvariable API_KEY auf Ihren API-Schlüssel und PROJECT_ID auf Ihre Projekt-ID gesetzt wird.

#!/bin/bash

URL="https://axe.deque.com/api-pub/watcher/downloadable/report"
MAX_ATTEMPTS=20
DELAY=5
TEMP_FILE=$(mktemp)

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
    echo "Attempt $i..."
    
    # Get both status and response
    STATUS=$(curl -s -w '%{http_code}' -L -H "Accept: application/json" -H "X-API-Key: $API_KEY" -o "$TEMP_FILE" "$URL?project_id=$PROJECT_ID")
    
    case $STATUS in
        200)
            echo "Success!"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 0
            ;;
        202)
            echo "Still processing, waiting ${DELAY}s..."
            sleep $DELAY
            ;;
        *)
            echo "Error: HTTP $STATUS"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 1
            ;;
    esac
done

echo "Timeout after $MAX_ATTEMPTS attempts"
rm "$TEMP_FILE"
exit 1