Ergebnisse programmgesteuert erhalten

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

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