Tag di query estesi
Panoramica
Per impostazione predefinita, il servizio DICOM supporta l'esecuzione di query sui tag DICOM specificati nell'istruzione conformità. Abilitando i tag di query estesi, l'elenco di tag può essere facilmente espanso in base alle esigenze dell'applicazione.
Usando le API elencate di seguito, gli utenti possono indicizzare i propri studi DICOM, serie e istanze in tag DICOM standard e privati, in modo che possano essere specificati nelle query QIDO-RS.
API
Versione: v1
Per gestire i tag supportati in un'istanza del servizio DICOM specificata, sono stati aggiunti gli endpoint API seguenti.
| API | Descrizione |
|---|---|
| POST .../extendedquerytags | Aggiungere tag di query estesi |
| GET .../extendedquerytags | Elencare i tag di query estesi |
| GET .../extendedquerytags/{tagPath} | Ottenere il tag di query estesa |
| DELETE .../extendedquerytags/{tagPath} | Eliminare il tag di query estesa |
| PATCH .../extendedquerytags/{tagPath} | Aggiornare il tag di query estesa |
| GET .../extendedquerytags/{tagPath}/errors | Elencare gli errori dei tag di query estesi |
| GET .../operations/{operationId} | Ottenere l'operazione |
Aggiungere tag di query estesi
Aggiunge uno o più tag di query estesi e avvia un'operazione a esecuzione prolungata che reindexa le istanze DICOM correnti con i tag specificati.
POST .../extendedquerytags
Intestazione della richiesta
| Nome | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
| Content-Type | True | string |
application/json è supportato |
Testo della richiesta
| Nome | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
| Corpo |
Tag query esteso per l'aggiunta[] |
Limitazioni
Sono supportati i tipi VR seguenti:
| VR | Descrizione | Corrispondenza valore singolo | Corrispondenza intervallo | Corrispondenza fuzzy |
|---|---|---|---|---|
| AE | Entità applicazione | X | ||
| AS | Stringa di età | X | ||
| CS | Stringa di codice | X | ||
| DA | Data | X | X | |
| DS | Stringa decimale | X | ||
| DT | Data/Ora | X | X | |
| FD | Doppia virgola mobile | X | ||
| FL | Singolo a virgola mobile | X | ||
| IS | Stringa integer | X | ||
| LO | Stringa lunga | X | ||
| PN | Nome persona | X | X | |
| SH | Stringa breve | X | ||
| SL | Segno lungo | X | ||
| SS | Corto firmato | X | ||
| TM | Ora | X | X | |
| Interfaccia utente | Identificatore univoco | X | ||
| UL | Unsigned Long | X | ||
| Stati Uniti | Unsigned Short | X |
Nota
I tag sequenziali, che sono tag con un tag di tipo Sequence of Items (SQ), non sono attualmente supportati. È possibile aggiungere fino a 128 tag di query estesi.
Risposte
| Nome | Tipo | Descrizione |
|---|---|---|
| 202 (Accettato) | Informazioni di riferimento sulle operazioni | Sono stati aggiunti tag di query estesi e un'operazione a esecuzione prolungata è stata avviata per reindicizzare le istanze DICOM esistenti |
| 400 (Richiesta non valida) | Il corpo della richiesta contiene dati non validi | |
| 409 (Conflitto) | Uno o più tag di query richiesti sono già supportati |
Elencare i tag di query estesi
Elenchi di tutti i tag di query estesi.
GET .../extendedquerytags
Risposte
| Nome | Tipo | Descrizione |
|---|---|---|
| 200 (OK) |
Tag di query estesa[] |
Restituisce tag di query estesi |
Ottenere un tag di query estesa
Ottenere un tag di query esteso.
GET .../extendedquerytags/{tagPath}
Parametri URI
| Nome | In | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|---|
| tagPath | path | True | string | tagPath è il percorso del tag, che può essere tag o parola chiave. Ad esempio, l'ID paziente è rappresentato da 00100020 o PatientId |
Risposte
| Nome | Tipo | Descrizione |
|---|---|---|
| 200 (OK) | Tag di query estesa | Tag di query estesa con l'oggetto specificato tagPath |
| 400 (Richiesta non valida) | Percorso tag richiesto non valido | |
| 404 (non trovato) | Tag di query estesa con tagPath richiesto non trovato |
Eliminare il tag di query estesa
Eliminare un tag di query estesa.
DELETE .../extendedquerytags/{tagPath}
Parametri URI
| Nome | In | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|---|
| tagPath | path | True | string | tagPath è il percorso del tag, che può essere tag o parola chiave. Ad esempio, l'ID paziente è rappresentato da 00100020 o PatientId |
Risposte
| Nome | Tipo | Descrizione |
|---|---|---|
| 204 (No Content (Nessun contenuto)) | Il tag di query esteso con tagPath richiesto è stato eliminato correttamente. | |
| 400 (Richiesta non valida) | Il percorso del tag richiesto non è valido. | |
| 404 (non trovato) | Tag di query estesa con tagPath richiesto non trovato |
Aggiornare il tag di query estesa
Aggiornare un tag di query esteso.
PATCH .../extendedquerytags/{tagPath}
Parametri URI
| Nome | In | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|---|
| tagPath | path | True | string | tagPath è il percorso del tag, che può essere tag o parola chiave. Ad esempio, l'ID paziente è rappresentato da 00100020 o PatientId |
Intestazione della richiesta
| Nome | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
| Content-Type | True | string |
application/json è supportato. |
Testo della richiesta
| Nome | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
| Corpo | Tag di query estesa per l'aggiornamento |
Risposte
| Nome | Tipo | Descrizione |
|---|---|---|
| 20 (OK) | Tag di query estesa | Tag di query esteso aggiornato |
| 400 (Richiesta non valida) | Percorso o corpo del tag richiesto non valido | |
| 404 (non trovato) | Tag di query estesa con tagPath richiesto non trovato |
Elencare gli errori dei tag di query estesi
Elenca gli errori in un tag di query esteso.
GET .../extendedquerytags/{tagPath}/errors
Parametri URI
| Nome | In | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|---|
| tagPath | path | True | string | tagPath è il percorso del tag, che può essere tag o parola chiave. Ad esempio, l'ID paziente è rappresentato da 00100020 o PatientId |
Risposte
| Nome | Tipo | Descrizione |
|---|---|---|
| 200 (OK) |
Errore tag di query estesa[] |
Elenco degli errori dei tag di query estesi associati al tag |
| 400 (Richiesta non valida) | Percorso tag richiesto non valido | |
| 404 (non trovato) | Tag di query estesa con tagPath richiesto non trovato |
Operazione Get
Ottenere un'operazione a esecuzione prolungata.
GET .../operations/{operationId}
Parametri URI
| Nome | In | Obbligatoria | Tipo | Descrizione |
|---|---|---|---|---|
| operationId | path | True | string | ID operazione |
Risposte
| Nome | Tipo | Descrizione |
|---|---|---|
| 200 (OK) | Operazione | Operazione completata per l'ID specificato |
| 202 (Accettato) | Operazione | Operazione in esecuzione per l'ID specificato |
| 404 (non trovato) | L'operazione non viene trovata |
QIDO con tag di query estesi
Stato tag
Lo stato del tag di query estesa indica lo stato corrente. Quando viene aggiunto per la prima volta un tag di query estesa, lo stato viene impostato su Addinge viene avviata un'operazione a esecuzione prolungata per reindicizzare le istanze DICOM esistenti. Al termine dell'operazione, lo stato del tag viene aggiornato a Ready. Il tag di query estesa può ora essere usato in QIDO.
Ad esempio, se viene aggiunto il tag Manufacturer Model Name (0008.1090) e in Ready stato, in seguito alle query seguenti è possibile usare per filtrare le istanze archiviate in base al nome del modello del produttore.
../instances?ManufacturerModelName=Microsoft
Possono anche essere usati con tag esistenti. Ad esempio:
../instances?00081090=Microsoft&PatientName=Jo&fuzzyMatching=true
Stato query tag
QueryStatus indica se QIDO è consentito per il tag. Quando un'operazione di reindicizzazione non riesce a elaborare una o più istanze DICOM per un tag, queryStatus del tag viene impostata automaticamente Disabled . È possibile scegliere di ignorare gli errori di indicizzazione e consentire alle query di usare questo tag impostando su tramite l'API Update Extended Query Tag .You can choose to ignore indexing errors and allow queries to use this tag by setting the QueryStatus su Enabled via Update Extended Query Tag API. Tutte le richieste QIDO che fanno riferimento ad almeno un tag abilitato manualmente includeranno il set di tag con errori di indicizzazione nell'intestazione erroneous-dicom-attributesdella risposta .
Si supponga, ad esempio, che il tag PatientAge di query estesa abbia avuto errori durante la reindicizzazione, ma sia stato abilitato manualmente. Per la query seguente, è possibile visualizzare PatientAge nell'intestazione erroneous-dicom-attributes .
../instances?PatientAge=035Y
Definizioni
Tag di query estesa
Tag DICOM che sarà supportato per QIDO-RS.
| Nome | Tipo | Descrizione |
|---|---|---|
| Percorso | string | Percorso del tag, in genere composto da ID gruppo e ID elemento. Ad esempio, PatientId (0010.0020) ha percorso 00100020 |
| VR | string | Rappresentazione del valore di questo tag |
| PrivateCreator | string | Codice di identificazione dell'implementatore di questo tag privato |
| Level | Livello di tag di query estesa | Livello di tag di query estesa |
| Stato | Stato tag di query estesa | Stato del tag di query estesa |
| QueryStatus | Stato query con tag di query estesa | Stato della query del tag di query esteso |
| Errors | Informazioni di riferimento sugli errori dei tag di query estesa | Riferimento agli errori dei tag di query estesi |
| Operazione | Informazioni di riferimento sulle operazioni | Riferimento a un'operazione a esecuzione prolungata |
L'esempio di codice 1 è un tag standard (0008.0070) nello Ready stato.
{
"status": "Ready",
"level": "Instance",
"queryStatus": "Enabled",
"path": "00080070",
"vr": "LO"
}
L'esempio di codice 2 è un tag standard (0010,1010) nello Adding stato. Un'operazione con ID 1a5d0306d9624f699929ee1a59ed57a0 è in esecuzione su di essa e 21 errori si sono verificati finora.
{
"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"
}
Informazioni di riferimento sulle operazioni
Riferimento a un'operazione a esecuzione prolungata.
| Nome | Tipo | Descrizione |
|---|---|---|
| ID | string | ID operazione |
| Href | string | URI per l'operazione |
Operazione
Rappresenta un'operazione a esecuzione prolungata.
| Nome | Tipo | Descrizione |
|---|---|---|
| OperationId | string | ID operazione |
| Tipo operazione | Tipo di operazione | Tipo dell'operazione a esecuzione prolungata |
| CreatedTime | string | Ora di creazione dell'operazione |
| LastUpdatedTime | string | Ora dell'ultimo aggiornamento dell'operazione |
| Stato | Stato operazione | Rappresenta lo stato di runtime dell'operazione |
| PercentComplete | Integer | Percentuale di lavoro completata dall'operazione |
| Risorse | string[] |
Raccolta di percorsi di risorse che l'operazione sta creando o modificando |
L'esempio di codice seguente è un'operazione di reindicizzazione in esecuzione.
{
"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
}
Stato dell'operazione
Rappresenta uno stato di runtime dell'operazione a esecuzione prolungata.
| Nome | Tipo | Descrizione |
|---|---|---|
| NotStarted | string | L'operazione non viene avviata |
| In esecuzione | string | L'operazione è in esecuzione e non è ancora stata completata |
| Completato | string | L'operazione è stata completata correttamente |
| Non riuscito | string | L'operazione è stata arrestata prematuramente dopo aver rilevato uno o più errori |
Errore di tag di query estesa
Errore che si è verificato durante un'operazione di indicizzazione dei tag di query estesa.
| Nome | Tipo | Descrizione |
|---|---|---|
| StudyInstanceUid | string | UID dell'istanza di studio in cui si sono verificati errori di indicizzazione |
| SeriesInstanceUid | string | UID dell'istanza della serie in cui si sono verificati errori di indicizzazione |
| SopInstanceUid | string | UID dell'istanza sop in cui si sono verificati errori di indicizzazione |
| CreatedTime | string | Ora in cui si è verificato l'errore (UTC) |
| ErrorMessage | string | Messaggio di errore |
L'esempio di codice seguente contiene un errore di lunghezza del valore imprevisto in un'istanza DICOM. Si è verificato al 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."
}
Informazioni di riferimento sugli errori dei tag di query estesi
Riferimento agli errori dei tag di query estesi.
| Nome | Tipo | Descrizione |
|---|---|---|
| Conteggio | Integer | Numero totale di errori nel tag di query estesa |
| Href | string | URI per gli errori dei tag di query estesi |
Tipo di operazione
Tipo di operazione a esecuzione prolungata.
| Nome | Tipo | Descrizione |
|---|---|---|
| Reindicizzare | string | Operazione di reindicizzazione che aggiorna gli indici per i dati aggiunti in precedenza in base ai nuovi tag |
Stato tag di query estesa
Stato del tag di query esteso.
| Nome | Tipo | Descrizione |
|---|---|---|
| Aggiunta | string | È stato aggiunto il tag di query estesa e un'operazione a esecuzione prolungata reindicizzare le istanze DICOM esistenti |
| Ready | string | Il tag di query estesa è pronto per QIDO-RS |
| Deleting | string | Il tag di query estesa viene eliminato |
Livello di tag di query estesa
Livello della gerarchia di informazioni DICOM in cui si applica questo tag.
| Nome | Tipo | Descrizione |
|---|---|---|
| Istanza | string | Il tag di query estesa è rilevante a livello di istanza |
| Serie | string | Il tag di query estesa è rilevante a livello di serie |
| Studiare | string | Il tag di query estesa è rilevante a livello di studio |
Stato della query con tag di query estesa
Stato della query del tag di query esteso.
| Nome | Tipo | Descrizione |
|---|---|---|
| Disabled | string | Non è consentito eseguire query sul tag di query estesa |
| Attivato | string | È consentito eseguire query sul tag di query estesa |
Nota
Gli errori durante l'operazione di reindicizzazione disabilitano QIDO nel tag di query estesa. È possibile chiamare l'API Update Extended Query Tag per abilitarla.
Tag di query estesa per l'aggiornamento
Rappresenta il tag di query esteso per l'aggiornamento.
| Nome | Tipo | Descrizione |
|---|---|---|
| QueryStatus | Stato query con tag di query estesa | Stato della query del tag di query estesa |
Tag di query estesa per l'aggiunta
Rappresenta il tag di query esteso per l'aggiunta.
| Nome | Obbligatorio | Tipo | Descrizione |
|---|---|---|---|
| Percorso | True | string | Percorso del tag, in genere composto dall'ID gruppo e dall'ID elemento ( PatientId 0010.0020) ha percorso 00100020 |
| VR | string | Rappresentazione del valore di questo tag. È facoltativo per il tag standard e obbligatorio per il tag privato | |
| PrivateCreator | string | Codice di identificazione dell'implementatore di questo tag privato. Impostato solo quando il tag è un tag privato | |
| Level | Vero | Livello di tag di query estesa | Rappresenta la gerarchia in cui questo tag è rilevante. Deve essere uno studio, una serie o un'istanza |
L'esempio di codice 1MicrosoftPC definisce il tag privato (0401.1001) con la rappresentazione del SS valore a livello di istanza.
{
"Path": "04011001",
"VR": "SS",
"PrivateCreator": "MicrosoftPC",
"Level": "Instance"
}
L'esempio di codice 2 usa il tag standard con la parola chiave ManufacturerModelName con la LO rappresentazione del valore definita a livello di serie.
{
"Path": "ManufacturerModelName",
"VR": "LO",
"Level": "Series"
}
L'esempio di codice 3 usa il tag standard (0010.0040) ed è definito sugli studi. La rappresentazione del valore è già definita dallo standard DICOM.
{
"Path": "00100040",
"Level": "Study"
}
Riepilogo
Questo articolo concettuale offre una panoramica della funzionalità Tag di query estesa all'interno del servizio DICOM.
Passaggi successivi
Per altre informazioni sulla distribuzione del servizio DICOM, vedere
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per