Ergebnisse programmgesteuert abrufen

Migration zur Sessions- und Ergebnisse-API

Die neue Sessions- und Ergebnisse-API ersetzt diesen Endpunkt durch zwei separate Endpunkte: einen zum Auflisten von Sitzungen für ein Projekt und einen zum Abrufen von Ergebnissen für eine bestimmte Sitzung. Dieses Zwei-Schritt-Modell gibt Ihnen Zugriff auf alle Sitzungen über Zweige und Commits hinweg, nicht nur auf die jüngste.

Äquivalente Anfrage mit format=summary

Der format=summary-Modus des Ergebnisse-Endpunkts liefert die gleiche JSON-Struktur wie dieser Endpunkt. Um eine bestehende Anfrage zu replizieren, suchen Sie zuerst die Sitzung, die Ihrem Zweig oder Commit entspricht, und fordern Sie dann deren Ergebnisse an:

1. Sitzungen auflisten um die session_id für den Zweig oder Commit, der Sie interessiert, zu finden, 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, nicht 202 Processing wie dieser Endpunkt. Wenn Ihr bestehender Code auf eine 202-Antwort prüft, 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 vollständige Detailinformationen auf Problem-Ebene über das hinaus wünschen, was die Zusammenfassung bietet, verwenden Sie format=full, um Ergebnisse in Universelles JSON (gemeinsames Exportformat) abzurufen. Dieses Format schließt alle während der Sitzung gefundenen Zugänglichkeitsprobleme ein: einzelne Verstöße, unvollständige Überprüfungen, Bestätigungen und unzutreffende Regeln, geordnet nach Seite.

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

Der herunterladbare Berichte REST-Dienst ermöglicht es Ihnen, eine Zusammenfassung Ihrer Barrierefreiheitsergebnisse aus dem Axe Developer Hub als JSON-Daten herunterzuladen, um sie weiterzuverarbeiten oder in andere Software zu importieren. Der GET-Dienst erfordert zwei Parameter:

• API-Schlüssel - Finden Sie einen persönlichen API-Schlüssel, der Ihrem Projekt entspricht, oder fügen Sie im Axe Account Portal einen neuen API-Schlüssel hinzu. Wählen Sie einen API-Schlüssel für Axe Developer Hub aus, wenn Ihr Projekt die Web-APIs, CLI oder Watcher verwendet. Verwenden Sie einen API-Schlüssel für Axe DevTools Mobile 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-Branch oder ein bestimmtes Git-Commit-SHA zu beschränken.

Anforderungszusammenfassung

• Endpunkt: https://axe.deque.com/api-pub/watcher/downloadable/report
• Anfrage: GET
• Header (erforderlich):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Abfrageparameter:
  • project_id (Erforderlich)
    • Beschreibung: Gibt die Projekt-ID für den Bericht des Projekts an, den Sie herunterladen möchten. Dieser Parameter ist erforderlich.
    • Beispielverwendung: 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-Branchnamen zurück.
    • Beispielverwendung: 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.
    • Beispielverwendung: 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 des Antwortkörpers

{
  "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.

Übergeordnete Struktur

source Objekt

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

test_details Objekt

Enthält Informationen über die Testausführung:

commit Objekt

Enthält Informationen über den Git-Commit, der dem Test zugeordnet ist:

devhub_summary Objekt

Enthält zusammengefasste Informationen über gefundene Barrierefreiheitsprobleme:

issue_count_by_impact Objekt

Teilt Probleme nach Auswirkungsgrad auf:

issue_count_by_rule Array

Jedes Objekt in diesem Array stellt eine Regel mit folgender Struktur dar:

Zusätzliche Antworten

202 Processing

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

Antworttext

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

429 Too Many Requests

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

Antworttext

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

400 Bad Request

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

Antworttext

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

401 Unauthorized

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

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

Antworttext

{
  "error": "Invalid API key"
}

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

Antworttext

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

404 Not Found

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

Der verwendete SHA-Wert mit commit_sha konnte nicht gefunden werden

Dieser Fehler zeigt an, dass es für diesen SHA keine Daten 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 mit einem Zweignamen zurückgegeben wird, der nicht existiert. (Siehe den nächsten Fehler.)

Antworttext

{
  "error": "Session not found"
}

Der angegebene Wert für branch_name existiert nicht

Diese Fehlermeldung entspricht der vorherigen Fehlermeldung (wenn der mit dem commit_sha Abfrageparameter angegebene SHA im Axe Developer Hub nicht vorhanden ist).

Antworttext

{
  "error": "Session not found"
}

Der angegebene Wert für project_id existiert nicht

Diese Fehlermeldung entspricht den vorherigen 404 Fehlern.

Antworttext

{
  "error": "Session not found"
}

Verarbeitung einer 202 Processing Antwort

Dieses Demonstrations-Shellskript zeigt, wie curl verwendet wird, um Ihren Bericht erneut anzufordern, wenn Sie eine 202 Processing-Antwort erhalten. Da Test-Suites möglicherweise zahlreiche Barrierefreiheitsverletzungen finden, benötigt unser System möglicherweise zusätzliche Zeit, um alle Ergebnisse zu verarbeiten, bevor der Bericht zum Download bereitsteht. Wir empfehlen, das folgende Beispiel zu verwenden, um ein Skript zu erstellen, das kontinuierlich ü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 ist.

#!/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