Rozszerzone tagi zapytań

Omówienie

Domyślnie usługa DICOM obsługuje wykonywanie zapytań dotyczących tagów DICOM określonych w instrukcji zgodności. Włączenie rozszerzonych tagów zapytań pozwala łatwo rozszerzyć listę tagów na podstawie potrzeb aplikacji.

Korzystając z poniższych interfejsów API, użytkownicy mogą indeksować swoje badania DICOM, serie i wystąpienia zarówno w standardowych, jak i prywatnych tagach DICOM, aby można je było określić w zapytaniach QIDO-RS.

Interfejsy API

Wersja: wersja 1

Aby ułatwić zarządzanie obsługiwanymi tagami w danym wystąpieniu usługi DICOM, dodano następujące punkty końcowe interfejsu API.

Interfejs API	Opis
POST .../extendedquerytags	Dodawanie tagów zapytań rozszerzonych
GET .../extendedquerytags	Wyświetlanie listy tagów zapytań rozszerzonych
GET .../extendedquerytags/{tagPath}	Uzyskiwanie tagu zapytania rozszerzonego
DELETE .../extendedquerytags/{tagPath}	Usuwanie tagu rozszerzonego zapytania
PATCH .../extendedquerytags/{tagPath}	Aktualizowanie tagu rozszerzonego zapytania
GET .../extendedquerytags/{tagPath}/errors	Wyświetlanie listy błędów tagu rozszerzonego zapytania
GET .../operations/{operationId}	Get Operation

Dodawanie tagów zapytań rozszerzonych

Dodaje co najmniej jeden rozszerzony tag zapytania i uruchamia długotrwałą operację, która ponownie indeksuje bieżące wystąpienia DICOM z określonymi tagami.

POST .../extendedquerytags

Nagłówek żądania

Nazwa	Wymagany	Typ	Opis
Content-Type	True	ciąg	application/json jest obsługiwana

Treść żądania

Nazwa	Wymagany	Typ	Opis
body		Rozszerzony tag zapytania do dodawania[]

Ograniczenia

Obsługiwane są następujące typy VR:

VR	Opis	Dopasowywanie pojedynczej wartości	Dopasowywanie zakresu	Dopasowywanie rozmyte
AE	Jednostka aplikacji	X
AS	Ciąg wieku	X
CS	Ciąg kodu	X
DA	Date	X	X
DS	Ciąg dziesiętny	X
DT	Data i godzina	X	X
FD	Zmiennoprzecinkowa podwójna	X
FL	Zmiennoprzecinkowa pojedyncza	X
IS	Ciąg liczby całkowitej	X
LO	Długi ciąg	X
PN	Nazwisko osoby	X		X
SH	Krótki ciąg	X
SL	Podpisano długo	X
SS	Podpisany krótki	X
TM	Godzina	X	X
Interfejs użytkownika	Unikatowy identyfikator	X
UL	Niepodpisany długi	X
USA	Niepodpisane krótkie	X

Uwaga

Tagi sekwencyjne, które są tagami pod tagiem typu Sekwencja elementów (SQ), nie są obecnie obsługiwane. Możesz dodać maksymalnie 128 rozszerzonych tagów zapytań.

Odpowiedzi

Nazwa	Typ	Opis
202 (zaakceptowane)	Odwołanie do operacji	Dodano rozszerzone tagi zapytania i rozpoczęto długotrwałą operację ponownego indeksowania istniejących wystąpień DICOM
400 (Nieprawidłowe żądanie)		Treść żądania zawiera nieprawidłowe dane
409 (Konflikt)		Co najmniej jeden żądany tag zapytania jest już obsługiwany

Wyświetlanie listy rozszerzonych tagów zapytań

Listy wszystkich rozszerzonych tagów zapytań.

GET .../extendedquerytags

Odpowiedzi

Nazwa	Typ	Opis
200 (OK)	Rozszerzony tag zapytania[]	Zwraca rozszerzone tagi zapytań

Uzyskiwanie rozszerzonego tagu zapytania

Uzyskiwanie rozszerzonego tagu zapytania.

GET .../extendedquerytags/{tagPath}

Parametry identyfikatora URI

Nazwa	W	Wymagany	Typ	Opis
tagPath	path	True	ciąg	tagPath to ścieżka tagu, który może być tagiem lub słowem kluczowym. Na przykład identyfikator pacjenta jest reprezentowany przez 00100020 lub PatientId

Odpowiedzi

Nazwa	Typ	Opis
200 (OK)	Rozszerzony tag zapytania	Rozszerzony tag zapytania z określonym tagiem tagPath
400 (Nieprawidłowe żądanie)		Żądana ścieżka tagu jest nieprawidłowa
404 (nie znaleziono)		Nie można odnaleźć rozszerzonego tagu zapytania z żądaną funkcją tagPath

Usuwanie rozszerzonego tagu zapytania

Usuń rozszerzony tag zapytania.

DELETE .../extendedquerytags/{tagPath}

Parametry identyfikatora URI

Nazwa	W	Wymagany	Typ	Opis
tagPath	path	True	ciąg	tagPath to ścieżka tagu, który może być tagiem lub słowem kluczowym. Na przykład identyfikator pacjenta jest reprezentowany przez 00100020 lub PatientId

Odpowiedzi

Nazwa	Typ	Opis
204 (brak zawartości)		Rozszerzony tag zapytania z żądanym tagiem tagPath został pomyślnie usunięty.
400 (Nieprawidłowe żądanie)		Żądana ścieżka tagu jest nieprawidłowa.
404 (nie znaleziono)		Nie można odnaleźć rozszerzonego tagu zapytania z żądaną funkcją tagPath

Aktualizowanie rozszerzonego tagu zapytania

Aktualizowanie rozszerzonego tagu zapytania.

PATCH .../extendedquerytags/{tagPath}

Parametry identyfikatora URI

Nazwa	W	Wymagany	Typ	Opis
tagPath	path	True	ciąg	tagPath to ścieżka tagu, który może być tagiem lub słowem kluczowym. Na przykład identyfikator pacjenta jest reprezentowany przez 00100020 lub PatientId

Nagłówek żądania

Nazwa	Wymagany	Typ	Opis
Content-Type	True	ciąg	application/json jest obsługiwana.

Treść żądania

Nazwa	Wymagany	Typ	Opis
body		Rozszerzony tag zapytania do aktualizowania

Odpowiedzi

Nazwa	Typ	Opis
20 (OK)	Rozszerzony tag zapytania	Zaktualizowany tag rozszerzonego zapytania
400 (Nieprawidłowe żądanie)		Żądana ścieżka lub treść tagu jest nieprawidłowa
404 (nie znaleziono)		Nie można odnaleźć rozszerzonego tagu zapytania z żądaną ścieżką tagPath

Wyświetlanie listy rozszerzonych błędów tagów zapytań

Wyświetla listę błędów w tagu zapytania rozszerzonego.

GET .../extendedquerytags/{tagPath}/errors

Parametry identyfikatora URI

Nazwa	W	Wymagany	Typ	Opis
tagPath	path	True	ciąg	tagPath to ścieżka tagu, która może być tagiem lub słowem kluczowym. Na przykład identyfikator pacjenta jest reprezentowany przez 00100020 lub PatientId

Odpowiedzi

Nazwa	Typ	Opis
200 (OK)	Błąd rozszerzonego tagu zapytania[]	Lista rozszerzonych błędów tagów zapytań skojarzonych z tagiem
400 (Nieprawidłowe żądanie)		Żądana ścieżka tagu jest nieprawidłowa
404 (nie znaleziono)		Nie można odnaleźć rozszerzonego tagu zapytania z żądaną ścieżką tagPath

Pobieranie operacji

Uzyskaj długotrwałą operację.

GET .../operations/{operationId}

Parametry identyfikatora URI

Nazwa	W	Wymagany	Typ	Opis
operationId	path	True	ciąg	Identyfikator operacji

Odpowiedzi

Nazwa	Typ	Opis
200 (OK)	Operacja	Ukończona operacja dla określonego identyfikatora
202 (zaakceptowane)	Operacja	Uruchomiona operacja dla określonego identyfikatora
404 (nie znaleziono)		Nie można odnaleźć operacji

QIDO z rozszerzonymi tagami zapytań

Stan tagu

Stan rozszerzonego tagu zapytania wskazuje bieżący stan. Po pierwszym dodaniu rozszerzonego tagu zapytania jego stan jest ustawiony na Adding, a długotrwała operacja jest uruchamiana w celu ponownego indeksowania istniejących wystąpień DICOM. Po zakończeniu operacji stan tagu zostanie zaktualizowany do Ready. Rozszerzony tag zapytania może być teraz używany w narzędziu QIDO.

Jeśli na przykład zostanie dodany tag Nazwa modelu producenta (0008 1090) i w Ready stanie, poniższe zapytania mogą służyć do filtrowania przechowywanych wystąpień według nazwy modelu producenta.

../instances?ManufacturerModelName=Microsoft

Mogą być one również używane z istniejącymi tagami. Na przykład:

../instances?00081090=Microsoft&PatientName=Jo&fuzzyMatching=true

Stan zapytania tagu

QueryStatus wskazuje, czy funkcja QIDO jest dozwolona dla tagu. Gdy operacja ponownego indeksowania nie może przetworzyć co najmniej jednego wystąpienia DICOM dla tagu, parametr QueryStatus tagu jest ustawiany automatycznie Disabled . Możesz zignorować błędy indeksowania i zezwolić na używanie tego tagu przez ustawienie QueryStatus wartości na Enabled wartość za pomocą interfejsu API tagu rozszerzonego zapytań aktualizacji . Wszystkie żądania QIDO odwołujące się do co najmniej jednego ręcznie włączonego tagu będą zawierać zestaw tagów z błędami indeksowania w nagłówku erroneous-dicom-attributesodpowiedzi .

Załóżmy na przykład, że rozszerzony tag PatientAge zapytania miał błędy podczas ponownego indeksowania, ale został włączony ręcznie. W przypadku następującego zapytania można zobaczyć PatientAge w nagłówku erroneous-dicom-attributes .

../instances?PatientAge=035Y

Definicje

Tag zapytania rozszerzonego

Tag DICOM, który będzie obsługiwany dla QIDO-RS.

Nazwa	Typ	Opis
Ścieżka	ciąg	Ścieżka tagu, zwykle składa się z identyfikatora grupy i identyfikatora elementu. Na przykład PatientId (0010 0020) ma ścieżkę 00100020
VR	ciąg	Reprezentacja wartości tego tagu
PrivateCreator	ciąg	Kod identyfikacyjny implementatora tego prywatnego tagu
Poziom	Rozszerzony poziom tagu zapytania	Poziom rozszerzonego tagu zapytania
Stan	Stan rozszerzonego tagu zapytania	Stan rozszerzonego tagu zapytania
Querystatus	Stan zapytania rozszerzonego tagu zapytania	Stan zapytania rozszerzonego tagu zapytania
błędy	Odwołanie do rozszerzonych błędów tagów zapytania	Odwołanie do błędów rozszerzonych tagów zapytań
Operacja	Odwołanie do operacji	Odwołanie do długotrwałej operacji

Przykładowy kod 1 to standardowy tag (0008 0070) w Ready stanie.

{
    "status": "Ready",
    "level": "Instance",
    "queryStatus": "Enabled",
    "path": "00080070",
    "vr": "LO"
}

Przykład kodu 2 to standardowy tag (0010 1010) w Adding stanie. Operacja z identyfikatorem 1a5d0306d9624f699929ee1a59ed57a0 jest uruchomiona na nim, a do tej pory wystąpiły 21 błędów.

{
    "status": "Adding",
    "level": "Study",
    "errors": {
        "count": 21,
        "href": "https://localhost:63838/extendedquerytags/00101010/errors"
    },
    "operation": {
        "id": "1a5d0306d9624f699929ee1a59ed57a0",
        "href": "https://localhost:63838/operations/1a5d0306d9624f699929ee1a59ed57a0"
    },
    "queryStatus": "Disabled",
    "path": "00101010",
    "vr": "AS"
}

Odwołanie do operacji

Odwołanie do długotrwałej operacji.

Nazwa	Typ	Opis
ID (Identyfikator)	ciąg	identyfikator operacji
Href	ciąg	Identyfikator URI operacji

Operacja

Reprezentuje długotrwałą operację.

Nazwa	Typ	Opis
Identyfikator operacji	ciąg	Identyfikator operacji
OperationType	Typ operacji	Typ długotrwałej operacji
CreatedTime	ciąg	Godzina utworzenia operacji
LastUpdatedTime	ciąg	Godzina ostatniej aktualizacji operacji
Stan	Stan operacji	Reprezentuje stan czasu wykonywania operacji
Percentcomplete	Liczba całkowita	Procent pracy wykonanej przez operację
Zasoby	ciąg[]	Kolekcja lokalizacji zasobów, które operacja tworzy lub manipuluje

Poniższy przykład kodu to uruchomiona operacja ponownego indeksowania.

{
    "resources": [
        "https://localhost:63838/extendedquerytags/00101010"
    ],
    "operationId": "a99a8b51-78d4-4fd9-b004-b6c0bcaccf1d",
    "type": "Reindex",
    "createdTime": "2021-10-06T16:40:02.5247083Z",
    "lastUpdatedTime": "2021-10-06T16:40:04.5152934Z",
    "status": "Running",
    "percentComplete": 10
}

Stan operacji

Reprezentuje stan czasu wykonywania długotrwałej operacji.

Nazwa	Typ	Opis
Niestartowane	ciąg	Operacja nie została uruchomiona
Uruchomienie	ciąg	Operacja jest wykonywana i nie została jeszcze zakończona
Ukończone	ciąg	Operacja została zakończona pomyślnie
Niepowodzenie	ciąg	Operacja została zatrzymana przedwcześnie po napotkaniu co najmniej jednego błędu

Błąd rozszerzonego tagu zapytania

Wystąpił błąd podczas rozszerzonej operacji indeksowania tagów zapytania.

Nazwa	Typ	Opis
Identyfikator StudyInstanceUid	ciąg	Identyfikator UID wystąpienia badania, w którym wystąpiły błędy indeksowania
Identyfikator SeriesInstanceUid	ciąg	Identyfikator UID wystąpienia serii, w którym wystąpiły błędy indeksowania
Identyfikator SopInstanceUid	ciąg	Identyfikator UID wystąpienia sop, w którym wystąpiły błędy indeksowania
CreatedTime	ciąg	Godzina wystąpienia błędu (UTC)
ErrorMessage	ciąg	Komunikat o błędzie

Poniższy przykład kodu zawiera nieoczekiwany błąd długości wartości w wystąpieniu DICOM. Wystąpił o godzinie 2021-10-06T16:41:44.4783136.

{
    "studyInstanceUid": "2.25.253658084841524753870559471415339023884",
    "seriesInstanceUid": "2.25.309809095970466602239093351963447277833",
    "sopInstanceUid": "2.25.225286918605419873651833906117051809629",
    "createdTime": "2021-10-06T16:41:44.4783136",
    "errorMessage": "Value length is not expected."
}

Odwołanie do rozszerzonych błędów tagów zapytania

Odwołanie do rozszerzonych błędów tagów zapytania.

Nazwa	Typ	Opis
Liczba	Liczba całkowita	Całkowita liczba błędów w tagu zapytania rozszerzonego
Href	ciąg	Identyfikator URI rozszerzonego tagu zapytania

Typ operacji

Typ długotrwałej operacji.

Nazwa	Typ	Opis
Ponowne indeksowanie	ciąg	Operacja ponownego indeksowania, która aktualizuje indeksy dla wcześniej dodanych danych na podstawie nowych tagów

Rozszerzony stan tagu zapytania

Stan rozszerzonego tagu zapytania.

Nazwa	Typ	Opis
Dodawanie	ciąg	Dodano tag rozszerzonego zapytania, a długotrwała operacja reindeksuje istniejące wystąpienia DICOM
Gotowy	ciąg	Rozszerzony tag zapytania jest gotowy do obsługi QIDO-RS
Usuwanie	ciąg	Tag rozszerzonego zapytania jest usuwany

Rozszerzony poziom tagu zapytania

Poziom hierarchii informacji DICOM, w którym ten tag ma zastosowanie.

Nazwa	Typ	Opis
Wystąpienie	ciąg	Tag rozszerzonego zapytania jest istotny na poziomie wystąpienia
Seria	ciąg	Tag rozszerzonego zapytania jest istotny na poziomie serii
Badania	ciąg	Tag rozszerzonego zapytania jest istotny na poziomie badania

Stan zapytania rozszerzonego tagu zapytania

Stan zapytania rozszerzonego tagu zapytania.

Nazwa	Typ	Opis
Disabled	ciąg	Rozszerzony tag zapytania nie może być odpytywane
Enabled (Włączony)	ciąg	Rozszerzony tag zapytania może być odpytywane

Uwaga

Błędy podczas operacji ponownego indeksowania wyłącza funkcję QIDO w tagu zapytania rozszerzonego. Aby ją włączyć, możesz wywołać interfejs API tagu rozszerzonego zapytania aktualizacji .

Rozszerzony tag zapytania na potrzeby aktualizowania

Reprezentuje rozszerzony tag zapytania do aktualizowania.

Nazwa	Typ	Opis
Querystatus	Stan zapytania rozszerzonego tagu zapytania	Stan zapytania rozszerzonego tagu zapytania

Rozszerzony tag zapytania do dodawania

Reprezentuje rozszerzony tag zapytania na potrzeby dodawania.

Nazwa	Wymagany	Typ	Opis
Ścieżka	True	ciąg	Ścieżka tagu, zwykle składająca się z identyfikatora grupy i identyfikatora elementu ( PatientId 0010 0020) ma ścieżkę 00100020
VR		ciąg	Reprezentacja wartości tego tagu. Jest ona opcjonalna dla tagu standardowego i wymagana dla tagu prywatnego
PrivateCreator		ciąg	Kod identyfikacyjny implementatora tego prywatnego tagu. Ustawiane tylko wtedy, gdy tag jest tagiem prywatnym
Poziom	Prawda	Rozszerzony poziom tagu zapytania	Reprezentuje hierarchię, w której ten tag jest odpowiedni. Powinna być jedną z serii, serii lub wystąpień

Przykład kodu 1MicrosoftPC definiuje tag prywatny (0401 1001) z reprezentacją SS wartości na poziomie wystąpienia.

{
    "Path": "04011001",
    "VR": "SS",
    "PrivateCreator": "MicrosoftPC",
    "Level": "Instance"
}

Przykład kodu 2 używa tagu standardowego ze słowem kluczowym ManufacturerModelName z reprezentacją LO wartości zdefiniowaną na poziomie serii.

{
    "Path": "ManufacturerModelName",
    "VR": "LO",
    "Level": "Series"
}

Przykład kodu 3 używa tagu standardowego (0010 0040) i jest definiowany na badaniach. Reprezentacja wartości jest już zdefiniowana przez standard DICOM.

{
    "Path": "00100040",
    "Level": "Study"
}

Podsumowanie

Ten koncepcyjny artykuł zawiera omówienie funkcji tagu rozszerzonego zapytania w usłudze DICOM.

Następne kroki

Aby uzyskać więcej informacji na temat wdrażania usługi DICOM, zobacz

Wdrażanie usługi DICOM na platformie Azure

Używanie interfejsów API DICOMweb™Standard z usługą DICOM