Ottieni Risultati Programmicamente

Il servizio REST di servizio REST dei report scaricabili ti permette di scaricare un riepilogo dei risultati di accessibilità del tuo Axe Developer Hub come dati JSON, per ulteriori elaborazioni o importazione in altri software. Il servizio GET ha due parametri obbligatori:

• Chiave API - Trova una chiave API personale corrispondente al tuo progetto o aggiungi una nuova chiave API nel Portale Account Axe. Scegli una chiave API di Axe Developer Hub se il tuo progetto utilizza le web API, CLI o Watcher. Usa una chiave API di Axe DevTools Mobile per i progetti mobili.
• ID Progetto - Fornisci l'ID del progetto per i dati del progetto corrispondenti che desideri scaricare. Trova il tuo ID progetto in Axe Developer Hub.

Puoi usare due parametri opzionali per limitare la tua query a un ramo Git specifico o a un specifico SHA del commit Git.

Riepilogo Richiesta

• Endpoint: https://axe.deque.com/api-pub/watcher/downloadable/report
• Richiesta: GET
• Intestazioni (Obbligatorie):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Parametri di query:
  • project_id (Obbligatorio)
    • Descrizione: Specifica l'ID del progetto per il report del progetto che desideri scaricare. Questo parametro è obbligatorio.
    • Esempio d'uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>
  • branch_name (Opzionale)
    • Descrizione: Restituisce il report scaricabile per il nome del ramo Git specificato.
    • Esempio d'uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&branch_name=<GIT_BRANCH>
  • commit_sha (Opzionale)
    • Descrizione: Restituisce il report scaricabile per lo SHA del commit Git specificato.
    • Esempio d'uso: GET https://axe.deque.com/api-pub/watcher/downloadable/report?project_id=<DEVHUB_PROJECT_ID>&commit_sha=<GIT_COMMIT_SHA>

Esempio di Richiesta curl

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

Esempio del Corpo della Risposta

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

Oggetto della Risposta

Le sezioni seguenti descrivono i JSON object nel corpo della risposta.

Struttura di Livello Superiore

Oggetto source

Contiene informazioni sul prodotto che ha generato il report:

Oggetto test_details

Contiene informazioni sull'esecuzione del test:

Oggetto commit

Contiene informazioni sul commit Git associato al test:

Oggetto devhub_summary

Contiene informazioni riassuntive sui problemi di accessibilità trovati:

Oggetto issue_count_by_impact

Analizza i problemi per livello di impatto:

Array issue_count_by_rule

Ogni oggetto in questo array rappresenta una regola con la seguente struttura:

Risposte aggiuntive

202 Processing

Questa risposta indica che il rapporto è ancora in fase di generazione e che è necessario riprovare dopo un'attesa.

Corpo della risposta

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

400 Bad Request

Il valore fornito per commit_sha non è un valore SHA-1.

Corpo della risposta

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

401 Unauthorized

Uno dei seguenti messaggi di errore accompagnerà la risposta 401 Unauthorized.

La chiave API specificata non è valida

Corpo della risposta

{
  "error": "Invalid API key"
}

Non c'è intestazione richiesta con una chiave API:

Corpo della risposta

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

404 Not Found

Uno dei seguenti messaggi di errore accompagnerà la risposta 404 Not Found.

Il valore SHA utilizzato con commit_sha non è stato trovato

Questo errore indica che non ci sono dati per questo SHA nei dati dell'Axe Developer Hub, il che di solito significa che la suite di test non è stata eseguita contro questo commit Git. Nota che questo è lo stesso errore restituito con un nome di branch che non esiste. (Vedi il prossimo errore.)

Corpo della risposta

{
  "error": "Session not found"
}

Il valore fornito per branch_name non esiste

Questa risposta di errore è la stessa del precedente errore (se lo SHA fornito con il parametro di query commit_sha non esiste nei dati di Axe Developer Hub).

Corpo della risposta

{
  "error": "Session not found"
}

Il valore fornito per project_id non esiste

Questa risposta di errore è la stessa dei precedenti errori 404.

Corpo della risposta

{
  "error": "Session not found"
}

Gestire una Risposta 202 Processing

Questo script dimostrativo mostra come utilizzare curl per richiedere nuovamente il tuo report se ricevi una risposta 202 Processing. Poiché le suite di test possono trovare numerose violazioni di accessibilità, il nostro sistema potrebbe richiedere ulteriore tempo per elaborare tutti i risultati prima che il report sia pronto per il download. Ti consigliamo di utilizzare l'esempio seguente per creare uno script che riprovi continuamente a vedere se i risultati sono disponibili. Riproverà la richiesta fino a 20 volte, con un ritardo di cinque secondi tra i tentativi.

L'esempio richiede che la variabile d'ambiente API_KEY sia impostata sulla tua chiave API e PROJECT_ID sia impostata sul tuo ID progetto.

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