Sprawdzanie stanu analizy

Artykuł
03/27/2023

Adres URL jest zwracany w nagłówku Location jako część odpowiedzi na żądanie do interfejsu API analyze. Jest on używany do tworzenia zapytania za pośrednictwem metody GET protokołu HTTP na potrzeby stanu zadania analizy. Po zakończeniu zadania analizy treść odpowiedzi będzie zawierać adres URL lub listę adresów URL, z których można pobrać dane wyjściowe wyników. Wywołuj ten identyfikator URI do momentu zwrócenia kodu stanu HTTP 200. Mimo że zadanie jest uruchomione, kod stanu HTTP 202 będzie zwracany wraz z nagłówkiem Location zawierającym ten sam identyfikator URI, który został zwrócony z procesu analyze. Po zwróceniu odpowiedzi o wartość 200 właściwości resultFileUris będzie obejmowała jedną lokalizację możliwą do pobrania lub listę takich lokalizacji w pliku ZIP. Plik używający formatu SARIF (Static Analysis Results Interchange Format) w wersji 2 znajduje się w pliku ZIP do pobrania, który jest sformatowanym plikiem JSON zawierającym wyniki analizy. Treść odpowiedzi będzie zawierać obiekt IssueSummary zawierający podsumowanie liczby znalezionych problemów.

Uwaga

Zaleca się odczekanie od 15 do 60 sekund między operacjami sprawdzania stanu. Wykonanie analizy zwykle trwa od 1 do 5 minut.
Ten interfejs API wymaga tokenu OAuth, który musi być tokenem tej samej aplikacji klienckiej, która zainicjowała zadanie analizy.

Nagłówki

Nazwisko	Typ	Oczekiwana wartość	Wymagane?
Autoryzacja	string	Token elementu nośnego OAuth 1 żądania aplikacji tożsamości Microsoft Entra.	yes
x-ms-tenant-id	Identyfikator GUID	Identyfikator dzierżawcy dla aplikacji.	tak
x-ms-correlation-id	GUID	Identyfikator przebiegu analizy. Identyfikator powinien być taki sam jak dla całej operacji wykonywania (przekazywanie, analiza, stan)	tak

Oczekiwane odpowiedzi

Kod stanu HTTP	Scenariusz	Wynik
200	Znaleziono jeden lub więcej wyników	Zobacz poniższy przykład. Zostanie zwrócony jeden wynik.
202	Trwa przetwarzanie	Zobacz poniższy przykład. Zostanie zwrócony jeden wynik.
403	Zabronione	Osoba przesyłająca żądanie nie jest tożsama z zleceniodawcą żądania analizy.
404	Nie znaleziono	Nie można znaleźć żądania analizy dotyczącego odwołania podanego w adresie URL.

Oczekiwane nagłówki odpowiedzi

Nazwisko	Typ	Oczekiwana wartość	Wymagane?
Lokalizacja	uri	Identyfikator URI, który ma być używany podczas wykonywania zapytania dotyczącego bieżącego stanu i do uzyskiwania wyników	tak

Oczekiwana treść odpowiedzi

W poniższej tabeli przedstawiono strukturę odpowiedzi na poszczególne żądania (tylko odpowiedzi HTTP 200 lub 202).

Właściwość	Typ	Oczekiwana wartość	Wymagane?
privacyPolicy	string	Identyfikator URI zasad ochrony prywatności.	Tak
Postęp	int	Wartość wynosząca od 0-100 procent wykonania, gdzie 10 oznacza, że przetwarzanie jest wykonane w około 10%.	Tak
runCorrelationId	GUID	Identyfikator żądania zawarty w poszczególnych żądaniach. Można go również użyć do skorelowania z żądaniem, jeśli jest to konieczne.	Tak
stan	string	Wartość `InProgress` jest zwracana, gdy zadanie jest wciąż przetwarzane. Wartość `Failed` jest zwracana, kiedy wystąpi błąd krytyczny podczas przetwarzania zadania na serwerze. Właściwość błędu powinna zawierać więcej szczegółów. Wartość `Finished` jest zwracana, gdy zadanie zakończy się powodzeniem bez problemów. Wartość `FinishedWithErrors` jest zwracana, gdy zadanie zostanie zakończone pomyślnie, ale nie udało się zakończyć jednej lub więcej reguł bez błędu. Jest to wyłącznie sygnał informujący, że raport może nie być kompletny. Microsoft wie o tych problemach na zapleczu i będzie pracować w celu ich zdiagnozowania i rozwiązania.	Tak
resultFileUris	tablica ciągów	Lista identyfikatorów URI umożliwiających bezpośrednie pobieranie danych wyjściowych. Powinna być jedna na każdy plik, który został dołączony do oryginalnego wywołania interfejsu API analizy.	Nie. Ta funkcja jest dostępna tylko wtedy, gdy przetwarzanie zostało ukończone.
issueSummary	IssueSummary	Właściwości wymienione poniżej	Nie. Ta funkcja jest dostępna tylko wtedy, gdy przetwarzanie zostało ukończone.
issueSummary.criticalIssueCount	int	Liczba zidentyfikowanych problemów o krytycznej ważności w wyniku	Tak
issueSummary.highIssueCount	int	Liczba zidentyfikowanych problemów o wysokiej ważności w wyniku	Tak
issueSummary.mediumIssueCount	int	Liczba zidentyfikowanych problemów o średniej ważności w wyniku	Tak
issueSummary.lowIssueCount	int	Liczba zidentyfikowanych problemów o niskiej ważności w wyniku	Tak
issueSummary.informationalIssueCount	int	Liczba zidentyfikowanych problemów o ważności informacyjnej w wyniku	Tak

Przykład: sprawdzanie stanu po zakończeniu

W tym przykładzie jest przesyłane wywołanie sprawdzania stanu z wynikiem oznaczającym ukończenie.

Żądanie

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

Zobacz także

Używanie internetowego interfejsu API narzędzia do sprawdzania usługi Power Apps
Pobieranie listy zestawów reguł
Pobieranie listy reguł
Przekazywanie pliku
Wywoływanie analizy

Udostępnij za pośrednictwem