Controleren op de status van de analyse

Artikel
03/27/2023

Een URL wordt geretourneerd als onderdeel van de header Location als antwoord op een verzoek aan de API analyze. Het moet worden gebruikt om de status van de analyseopdracht via HTTP GET aan te vragen. Wanneer de analysetaak is voltooid, bevat de responstekst de URL of lijst met URL's waarin de resultaatuitvoer kan worden gedownload. Blijf deze URI aanroepen totdat een HTTP-statuscode van 200 wordt geretourneerd. Terwijl de taak nog actief is, wordt een HTTP-statuscode van 202 geretourneerd met de Location-header met dezelfde URI die is geretourneerd van analyze. Zodra een 200-respons is geretourneerd, bevat de eigenschap resultFileUris de ene locatie of lijst met downloadbare locaties van de uitvoer, in een zipbestand. Er is een SARIF V2-bestand (Static Analysis Results Interchange Format) opgenomen in deze zipdownload (een JSON-bestand met de resultaten van de analyse). De responstekst bevat een IssueSummary-object dat een samenvatting bevat van het aantal gevonden problemen.

Notitie

U wordt aangeraden tussen 15 en 60 seconden te wachten tussen statuscontroles. De analyse duurt gewoonlijk 1 tot 5 minuten.
Voor deze API is een OAuth-token vereist dat een token moet zijn voor dezelfde clienttoepassing die de analysetaak heeft gestart.

Koppen

Naam	Type	Verwachte waarde	Vereist?
Autorisatie	string	Het OAuth 1-Bearer-token met toepassings-id-claim van Microsoft Entra.	yes
x-ms-tenant-id	GUID	De id van de tenant voor de toepassing.	ja
x-ms-correlation-id	GUID	De id voor de analyserun. U moet dezelfde id opgeven voor de volledige uitvoering (uploaden, analyseren, status)	ja

Verwachte responsen

HTTP-statuscode	Scenario	Resultaat
200	Er zijn een of meer resultaten gevonden	Zie het voorbeeld hieronder. Er wordt één resultaat geretourneerd.
202	Wordt nog verwerkt	Zie het voorbeeld hieronder. Er wordt één resultaat geretourneerd.
403	Verboden	De aanvrager is niet dezelfde als de opsteller van de analyseaanvraag.
404	Niet gevonden	Kan de analyseaanvraag niet vinden met de referentie in de URL.

Verwachte responsheaders

Naam	Type	Verwachte waarde	Vereist?
Location	uri	URI om te gebruiken bij het opvragen van de huidige status en om de resultaten te verkrijgen	ja

Verwachte responstekst

De volgende tabel geeft de structuur van de respons voor elke aanvraag weer (alleen HTTP 200- of 202-respons).

Eigenschap	Type	Verwachte waarde	Vereist?
privacyPolicy	string	De URI van het privacybeleid.	Ja
Voortgang	geheel getal (int)	Een waarde tussen 0-100 procent voltooid, waarbij 10 betekent dat de verwerking ongeveer 10% is voltooid.	Ja
runCorrelationId	GUID	De aanvraag-id die in elke aanvraag is opgenomen. Deze kan zo nodig worden gebruikt voor correlatie met de aanvraag.	Ja
status	string	`InProgress` wordt geretourneerd wanneer de taak nog wordt verwerkt. `Failed` wordt geretourneerd wanneer er een catastrofaal probleem was bij het verwerken van de taak op de server. Er moeten meer details te vinden zijn in de fouteigenschap. `Finished` wordt geretourneerd wanneer de taak zonder problemen is voltooid. `FinishedWithErrors` wordt geretourneerd wanneer de taak is voltooid, maar een of meer regels niet zonder fout zijn voltooid. Dit is puur een signaal voor u om te weten dat het rapport mogelijk niet volledig is. Microsoft is op de hoogte van deze problemen in de backend en werkt aan een diagnose en oplossing.	Ja
resultFileUris	matrix tekenreeksen	Een lijst met URI's waarmee de uitvoer rechtstreeks kan worden gedownload. Er moet er één per bestand zijn die is opgenomen in de oorspronkelijke analyse-API-aanroep.	Nee. Dit wordt alleen opgenomen wanneer de verwerking is voltooid.
issueSummary	IssueSummary	Eigenschappen hieronder vermeld	Nee. Dit wordt alleen opgenomen wanneer de verwerking is voltooid.
issueSummary.criticalIssueCount	geheel getal (int)	Aantal geïdentificeerde problemen met kritieke gevallen in het resultaat	Ja
issueSummary.highIssueCount	geheel getal (int)	Aantal geïdentificeerde problemen met gevallen met hoge prioriteit in het resultaat	Ja
issueSummary.mediumIssueCount	geheel getal (int)	Aantal geïdentificeerde problemen met gevallen met normale prioriteit in het resultaat	Ja
issueSummary.lowIssueCount	geheel getal (int)	Aantal geïdentificeerde problemen met gevallen met lage prioriteit in het resultaat	Ja
issueSummary.informationalIssueCount	geheel getal (int)	Aantal geïdentificeerde problemen met informatieve gevallen in het resultaat	Ja

Voorbeeld: statuscontrole wanneer klaar

Dit voorbeeld geeft een statuscontroleaanroep met als resultaat een voltooiing.

Aanvraag

GET [Geographical URI]/api/status/9E378E56-6F35-41E9-BF8B-C0CC88E2B832&api-version=1.0
Accept: application/json
Content-Type: application/json; charset=utf-8
x-ms-correlation-id: 9E378E56-6F35-41E9-BF8B-C0CC88E2B832
x-ms-tenant-id: F2E60E49-CB87-4C24-8D4F-908813B22506

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "privacyPolicy":"https://go.microsoft.com/fwlink/?LinkID=310140",
    "progress":100,
    "resultFileUris":["https://fakeblob.blob.core.windows.net/report-files/mySolution.zip?sv=2017-11-09&sr=b&sig=xyz&se=2019-06-11T20%3A27%3A59Z&sp=rd"],"runCorrelationId":"9E378E56-6F35-41E9-BF8B-C0CC88E2B832","status":"Finished","issueSummary":
    {
        "informationalIssueCount":0,
        "lowIssueCount":0,
        "mediumIssueCount":302,
        "highIssueCount":30,
        "criticalIssueCount":0
    }
}

Zie ook

De web-API Power Apps-controle gebruiken
De lijst met regelsets ophalen
De lijst met regels ophalen
Een bestand uploaden
Analyse aanroepen

Delen via