本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 在 HealthImaging 中搜尋 DICOM 資料
<a name="dicomweb-search"></a>

AWS HealthImaging 提供 [ DICOMweb QIDO-RS](https://www.dicomstandard.org/using/dicomweb/query-qido-rs) APIs 的表示法，以依病患 ID 搜尋研究、序列和執行個體，並接收其唯一識別符以供進一步使用。HealthImaging 的 DICOMweb QIDO-RS APIs 可讓您靈活地搜尋存放在 HealthImaging 中的資料，並提供與舊版應用程式的互通性。

**Important (重要)**  
HealthImaging 的 DICOMweb APIs 可用來傳回 QIDO-RS 的影像集資訊。除非另有說明，否則 HealthImaging DICOMweb APIs僅參考主要[影像集](getting-started-concepts.md#concept-image-set)。使用 HealthImaging [雲端原生動作，](https://docs.aws.amazon.com/healthimaging/latest/APIReference/API_Operations.html)或 DICOMweb 動作的選用影像集參數來擷取非主要影像集。HealthImaging 的 DICOMweb APIs 可用來傳回具有 DICOMweb 合規回應的影像集資訊。  
本節中列出的 APIs 是根據 Web 型醫療影像的 DICOMweb (QIDO-RS) 標準所建置。它們不會透過 AWS CLI 和 AWS SDKs提供。

## HealthImaging 的 DICOMweb 搜尋 API APIs
<a name="dicomweb-search-services"></a>

下表說明可用於在 HealthImaging 中搜尋資料之 DICOMweb QIDO-RS APIs 的所有 HealthImaging 表示法。


**HealthImaging 表示 DICOMweb QIDO-RS APIs**  

| 名稱 | 描述 | 
| --- | --- | 
| SearchDICOMStudies | 使用 GET 請求指定搜尋查詢元素，在 HealthImaging 中搜尋 DICOM 檢查。研究搜尋結果會以 JSON 格式傳回，依上次更新、日期遞減 （最晚到最舊） 排序。請參閱 [搜尋研究](dicomweb-search-studies.md)。 | 
| SearchDICOMSeries | 使用 GET 請求指定搜尋查詢元素，在 HealthImaging 中搜尋 DICOM 系列。系列搜尋結果會以 JSON 格式傳回，依遞增順序 Series Number (0020, 0011) （最舊到最新） 排序。請參閱 [搜尋系列](dicomweb-search-series.md)。 | 
| SearchDICOMInstances | 使用 GET 請求指定搜尋查詢元素，在 HealthImaging 中搜尋 DICOM 執行個體。執行個體搜尋結果會以 JSON 格式傳回，依遞增順序 Instance Number (0020, 0013) （最舊到最新） 排序。請參閱 [搜尋執行個體](dicomweb-search-instances.md)。 | 
| SearchDICOMStudyInstances | 透過使用 GET 請求指定搜尋查詢元素，在 HealthImaging 中搜尋研究中的所有 DICOM 執行個體。API 會以 JSON 格式傳回執行個體搜尋結果，依上次更新日期、遞減 （最晚到最舊） 排序。請參閱 [搜尋檢查的執行個體](dicomweb-search-study-instances.md)。 | 
| SearchDICOMAllSeries | 透過使用 GET 請求指定搜尋查詢元素，在 HealthImaging 中跨資料存放區搜尋所有 DICOM 系列。API 會以 JSON 格式傳回序列搜尋結果，依遞增順序 Series Number (0020,0011) （最舊到最新） 排序。請參閱 [搜尋所有系列](dicomweb-search-all-series.md)。 | 
| SearchDICOMAllInstances | 透過使用 GET 請求指定搜尋查詢元素，在 HealthImaging 中跨資料存放區搜尋所有 DICOM 執行個體。API 會以 JSON 格式傳回執行個體搜尋結果，依遞增順序 Instance Number (0020,0013) （最舊到最新） 排序。請參閱 [搜尋所有執行個體](dicomweb-search-all-instances.md)。 | 

## HealthImaging 支援的 DICOMweb 查詢類型
<a name="dicomweb-query-types"></a>

HealthImaging 支援研究、系列和 SOP 執行個體層級的 QIDO-RS 階層資源查詢。使用 HealthImaging 的 QIDO-RS 階層搜尋時：
+ 搜尋研究會傳回研究清單
+ 搜尋檢查的序列需要已知的 ，`StudyInstanceUID`並傳回序列清單
+ 搜尋執行個體清單需要已知 `StudyInstanceUID`和 `SeriesInstanceUID`

使用 HealthImaging，您可以執行 QIDO-RS 關聯式查詢，而無需在資源階層中指定所有父系 UIDs：
+ 搜尋檢查的執行個體不需要 `SeriesInstanceUID`。
+ 搜尋資料存放區中的所有序列不需要 `StudyInstanceUID`。
+ 搜尋資料存放區中的所有執行個體不需要 `StudyInstanceUID`或 `SeriesInstanceUID`。

下表說明在 HealthImaging 中搜尋資料的支援 QIDO-RS 查詢類型。


**HealthImaging 支援的 QIDO-RS 查詢類型**  

| 查詢類型 | 範例 | 
| --- | --- | 
| 屬性值查詢 | 搜尋 檢查中的所有序列，其中 `modality=CT`。<br />`.../studies/1.3.6.1.4.1.14519.5.2.1.6279.6001.101370605276577556143013894866/series?00080060=CT`<br />搜尋病患 ID 和檢查日期分別是這些值的所有檢查。<br />`…/studies?PatientID=11235813&StudyDate=20130509` | 
| 關鍵字查詢 | 使用 `SeriesInstanceUID`關鍵字搜尋所有序列。<br />`.../studies/1.3.6.1.4.1.14519.5.2.1.6279.6001.101370605276577556143013894866/series?SeriesInstanceUID=1.3.6.1.4.1.14519.5.2.1.6279.6001.101370605276577556143013894868` | 
| 標籤查詢 | 使用以群組/元素形式傳遞的查詢參數來搜尋標籤。<br />{group}{element}，例如 0020000D | 
| 範圍查詢 | `...?Modality=CT&StudyDate=AABBYYYY-BBCCYYYY` | 
| 使用 limit和 的結果分頁 offset | `.../studies?limit=1&offset=0&00080020=20000101`<br />您可以使用限制和位移參數來分頁搜尋回應。限制的預設值為 1000，最大值[AWS HealthImaging 端點和配額](endpoints-quotas.md)請參閱 。<br />最大限制 = 1000，最大位移 = 1，000，000 | 
| 萬用字元查詢 | 萬用字元查詢提供使用「\*」和「？」的搜尋彈性。「\*」符合任何字元序列 （包括零長度值） 和「？」 符合任何單一字元。<br />搜尋資料存放區中 StudyDescription 包含「Nuclear」的所有研究：<br />`.../studies?StudyDescription=*Nuclear*`<br />搜尋 StudyDescription 以「Nuclear」結尾的所有研究：<br />`.../studies?StudyDescription=*Nuclear`<br />搜尋所有研究，其中 StudyDescription 以「Nuclear」開頭：<br />`.../studies?StudyDescription=Nuclear*`<br />在 200965981 之後，搜尋 PatientID 完全有任何 3 個字元的所有研究：<br />`.../studies?PatientID=200965981???` | 
| FuzzyMatching 查詢 | 透過新增模糊比對選用查詢參數，在名稱 DICOM 屬性上啟用模糊比對 (PatientNamesReferringPhysicianName(0008，0090))：<br />`.../studies?fuzzymatching=true&PatientName="Thomas^Albert"`<br />此查詢會對 PatientName 值的任何部分執行不區分大小寫的字首。它會傳回具有 PatientName 值的結果，例如 "thomas"、"Albert"、"Thomasberg"、"Thomas^Albert"，但不傳回 "hom" 或 "ber"。 | 
| IncludeField 查詢 | 使用`includefield`查詢參數請求預設回應集以外的其他 DICOM 屬性。<br />依標籤傳回特定屬性：<br />`.../studies?PatientID=11235813&includefield=00101081&includefield=PatientWeight`<br />傳回所有可用的屬性：<br />`.../studies?PatientID=11235813&includefield=all`<br />使用虛線表示法傳回序列 (SQ) 子屬性：<br />`.../studies?PatientID=11235813&includefield=00080096.00080100`<br />傳回私有資料元素：<br />`.../instances?includefield=00191001&00190010=Philips` | 
| 關聯式查詢 | 在形式為 CT 的資料存放區中搜尋所有序列：<br />`.../series?Modality=CT`<br />搜尋研究日期為特定值之研究中的所有執行個體：<br />`.../studies/{{StudyInstanceUID}}/instances?StudyDate=20240101` | 

## 在 QIDO-RS 查詢中使用 IncludeField
<a name="dicomweb-includefield"></a>

`includefield` 查詢參數可讓您請求 HealthImaging QIDO-RS 查詢中預設回應集以外的其他 DICOM 屬性。您可以在研究、序列和執行個體層級使用 `includefield` 。

### 語法
<a name="dicomweb-includefield-syntax"></a>

使用下列 GET 請求格式，在您的 QIDO-RS 查詢中包含其他欄位：

```
GET .../studies?<query_params>&includefield=<tag_or_keyword>
GET .../studies/<StudyInstanceUID>/series?<query_params>&includefield=<tag_or_keyword>
GET .../studies/<StudyInstanceUID>/series/<SeriesInstanceUID>/instances?<query_params>&includefield=<tag_or_keyword>
```

您可以在單一請求中指定多個`includefield`參數：

```
GET .../studies?PatientID=11235813&includefield=00101081&includefield=00101030&includefield=00101010
```

### 支援 includefield 的值
<a name="dicomweb-includefield-values"></a>

下表說明 `includefield` 參數支援的值。


**支援的包含欄位值**  

| 值類型 | 說明 | 範例 | 
| --- | --- | --- | 
| DICOM 標籤 (8 個十六進位字元） | 依 GGGGEEEE 格式的標籤請求特定 DICOM 屬性。 | includefield=00081030 | 
| all | 請求資源層級的所有可用 DICOM 屬性。 | includefield=all | 
| 虛線 SQ 路徑 | 使用點表示法請求序列 (SQ) 屬性中的特定子屬性：<parent\_tag>.<child\_tag>。 | includefield=00080096.00080100 | 
| 私有資料元素標籤 | 請求私有標籤 (odd-group 元素）。需要 privateCreatorElement 參數。 | includefield=00191001 | 
| 標準 DICOM 屬性，包括大量資料 | 依標籤或關鍵字請求特定的單一或多個屬性。 | includefield=00102201 | 

### 行為和規則
<a name="dicomweb-includefield-behavior"></a>

下列規則適用於`includefield`查詢：
+ **預設回應** – 如果沒有 `includefield`，QIDO-RS 回應只會傳回標準屬性集。
+ **includefield=all** – 傳回請求層級的所有可用屬性。當 `all` 與其他`includefield`值結合時， `all`會優先。
+ **標籤上限** – 請求最多可包含 50 個`includefield`參數。
+ **重複標籤** – 重複`includefield`值會刪除並視為單一請求。
+ **無效或遺失標籤** – 如果請求的標籤不存在於 DICOM 資料中或無效，則會從回應中無提示地省略該標籤。仍會傳回其他有效的`includefield`屬性。

### 序列 (SQ) 屬性
<a name="dicomweb-includefield-sq"></a>

使用點符號來請求序列 (SQ) 屬性中的巢狀屬性：

```
includefield=<parent_SQ_tag>.<child_tag>
```

例如，若要在 ReferringPhysicianIdentificationSequence (0008，0096) 中擷取 CodeValue (0008，0100)：

```
GET .../studies?PatientID=11235813&includefield=00080096.00080100
```

支援多層級巢狀。例如：

```
includefield=00081115.00081199.00081150
```

### 私有標籤
<a name="dicomweb-includefield-private"></a>

所有資源層級都支援私有 DICOM 資料元素 (odd-group 標籤）。若要請求私有標籤，請包含`privateCreatorElement`查詢參數。

使用下列語法：

```
GET .../instances?includefield=<private_tag>&<creator_tag>=<creator_name>
```

例如：

```
GET .../instances?includefield=00191001&00190010=Philips
```

下列規則適用於私有標籤：
+ 如果請求私有`privateCreatorElement`標籤，則必須提供標籤和建立者名稱做為比對參數。
+ 如果`privateCreatorElement`找不到指定的 ，則會以無提示方式省略私有標籤。
+ 僅請求沒有私有資料元素的`privateCreatorElement`標籤，只會傳回建立者元素名稱和值。它不會傳回屬於該建立者區塊的所有標籤。

### 大量資料標籤
<a name="dicomweb-includefield-bulkdata"></a>

請求的二進位值大於 1 MB 的大量資料 VRs(OB、OD、O OF、OL、UN、OW、OV) DICOM 屬性`includefield`會傳回為原始二進位值，`bulkdataURI`而非原始二進位值。如需擷取大量資料的詳細資訊，請參閱[在 HealthImaging 中擷取 DICOM 大量資料](https://docs.aws.amazon.com/healthimaging/latest/devguide/dicom-retrieve-bulkdata.html)。

### 每個層級的 includefield= all return 是什麼？
<a name="dicomweb-includefield-all-levels"></a>

指定 `includefield=all` 時，回應會包含特定資源層級的所有屬性。

#### 研究層級 (includefield=all)
<a name="dicomweb-includefield-all-study"></a>

下表列出`includefield=all`指定 時，在研究層級傳回的所有屬性。


**includefield=all 的試驗層級屬性**  

| Tag | 名稱 | 虛擬實境 | 
| --- | --- | --- | 
| 00080005 | SpecificCharacterSet | CS | 
| 00080020 | StudyDate | DA | 
| 00080030 | StudyTime | TM | 
| 00080050 | AccessionNumber | SH | 
| 00080051 | IssuerOfAccessionNumberSequence | SQ | 
| 00080056 | InstanceAvailability | CS | 
| 00080061 | ModalitiesInStudy | CS | 
| 00080062 | SOPClassesInStudy | UI | 
| 00080090 | ReferringPhysicianName | PN | 
| 0008009C | ConsultingPhysicianName | PN | 
| 00080201 | TimezoneOffsetFromUTC | SH | 
| 00081030 | StudyDescription | LO | 
| 00081048 | PhysiciansOfRecord | PN | 
| 00081060 | NameOfPhysiciansReadingStudy | PN | 
| 00081080 | AdmittingDiagnosesDescription | LO | 
| 00081190 | RetrieveURL | UR | 
| 00100010 | PatientName | PN | 
| 00100020 | PatientID | LO | 
| 00100021 | IssuerOfPatientID | LO | 
| 00100022 | TypeOfPatientID | CS | 
| 00100026 | SourcePatientGroupIdentificationSequence | SQ | 
| 00100027 | GroupOfPatientsIdentificationSequence | SQ | 
| 00100028 | SubjectRelativePositionInImage | 美國 | 
| 00100030 | PatientBirthDate | DA | 
| 00100032 | PatientBirthTime | TM | 
| 00100033 | PatientBirthDateInAlternativeCalendar | LO | 
| 00100034 | PatientDeathDateInAlternativeCalendar | LO | 
| 00100035 | PatientAlternativeCalendar | CS | 
| 00100040 | PatientSex | CS | 
| 00100050 | PatientInsurancePlanCodeSequence | SQ | 
| 00100101 | PatientPrimaryLanguageCodeSequence | SQ | 
| 00100102 | PatientPrimaryLanguageModifierCodeSequence | SQ | 
| 00100200 | QualityControlSubject | CS | 
| 00100201 | QualityControlSubjectTypeCodeSequence | SQ | 
| 00100213 | StrainNomenclature | LO | 
| 00100214 | StrainStockNumber | LO | 
| 00100215 | StrainSourceRegistryCodeSequence | SQ | 
| 00100217 | StrainSource | LO | 
| 00100219 | StrainCodeSequence | SQ | 
| 00100223 | GeneticModificationsNomenclature | LO | 
| 00100229 | GeneticModificationsCodeSequence | SQ | 
| 00101001 | OtherPatientNames | PN | 
| 00101005 | PatientBirthName | PN | 
| 00101010 | PatientAge | AS | 
| 00101020 | PatientSize | DS | 
| 00101021 | PatientSizeCodeSequence | SQ | 
| 00101022 | PatientBodyMassIndex | DS | 
| 00101023 | MeasuredAPDimension | DS | 
| 00101024 | MeasuredLateralDimension | DS | 
| 00101030 | PatientWeight | DS | 
| 00101040 | PatientAddress | LO | 
| 00101060 | PatientMotherBirthName | PN | 
| 00101080 | MilitaryRank | LO | 
| 00101081 | BranchOfService | LO | 
| 00102000 | MedicalAlerts | LO | 
| 00102110 | 敏感 | LO | 
| 00102150 | CountryOfResidence | LO | 
| 00102152 | RegionOfResidence | LO | 
| 00102154 | PatientTelephoneNumbers | SH | 
| 00102160 | EthnicGroup | SH | 
| 00102180 | 職業 | SH | 
| 001021A0 | SmokingStatus | CS | 
| 001021C0 | PregnancyStatus | 美國 | 
| 001021D0 | LastMenstrualDate | DA | 
| 001021F0 | PatientReligiousPreference | LO | 
| 00102201 | PatientSpeciesDescription | LO | 
| 00102202 | PatientSpeciesCodeSequence | SQ | 
| 00102203 | PatientSexNeutered | CS | 
| 00102210 | AnatomicalOrientationType | CS | 
| 00102292 | PatientBreedDescription | LO | 
| 00102293 | PatientBreedCodeSequence | SQ | 
| 00102295 | BreedRegistrationNumber | LO | 
| 00102296 | BreedRegistryCodeSequence | SQ | 
| 00102297 | ResponsiblePerson | PN | 
| 00102298 | ResponsiblePersonRole | CS | 
| 00102299 | ResponsibleOrganization | LO | 
| 00109431 | ExaminedBodyThickness | 佛羅里達州 | 
| 0020000D | StudyInstanceUID | UI | 
| 00200010 | StudyID | SH | 
| 00201206 | NumberOfStudyRelatedSeries | IS | 
| 00201208 | NumberOfStudyRelatedInstances | IS | 
| 00321032 | RequestingPhysician | PN | 
| 00321033 | RequestingService | LO | 
| 00321060 | RequestedProcedureDescription | LO | 
| 00321070 | RequestedContrastAgent | LO | 
| 00380010 | AdmissionID | LO | 
| 00380016 | RouteOfAdmissions | LO | 
| 00380020 | AdmittingDate | DA | 
| 00380021 | AdmittingTime | TM | 
| 00380050 | SpecialNeeds | LO | 
| 00380060 | ServiceEpisodeID | LO | 
| 00380062 | ServiceEpisodeDescription | LO | 
| 00380300 | CurrentPatientLocation | LO | 
| 00380400 | PatientInstitutionResidence | LO | 
| 00380500 | PatientState | LO | 
| 00400244 | PerformedProcedureStepStartDate | DA | 
| 00400245 | PerformedProcedureStepStartTime | TM | 
| 00400250 | PerformedProcedureStepEndDate | DA | 
| 00400251 | PerformedProcedureStepEndTime | TM | 
| 00400253 | PerformedProcedureStepID | SH | 
| 00081032 | ProcedureCodeSequence | SQ | 
| 00100024 | IssuerOfPatientIDQualifiersSequence | SQ | 
| 00321034 | RequestingServiceCodeSequence | SQ | 
| 00321064 | RequestedProcedureCodeSequence | SQ | 
| 00401012 | ReasonForPerformedProcedureCodeSequence | SQ | 

#### 系列層級 (includefield=all)
<a name="dicomweb-includefield-all-series"></a>

下表列出指定 時傳回`includefield=all`的序列層級屬性。序列層級也會傳回上表中列出的所有研究層級屬性。


**includefield=all 的序列層級屬性**  

| Tag | 名稱 | 虛擬實境 | 
| --- | --- | --- | 
| 00080021 | SeriesDate | DA | 
| 00080031 | SeriesTime | TM | 
| 00080060 | 模態 | CS | 
| 00080064 | ConversionType | CS | 
| 00080068 | PresentationIntentType | CS | 
| 00080070 | 製造商 | LO | 
| 00080080 | InstitutionName | LO | 
| 00080082 | InstitutionCodeSequence | SQ | 
| 00081010 | StationName | SH | 
| 0008103E | SeriesDescription | LO | 
| 0008103F | SeriesDescriptionCodeSequence | SQ | 
| 00081040 | InstitutionalDepartmentName | LO | 
| 00081041 | InstitutionalDepartmentTypeCodeSequence | SQ | 
| 00081050 | PerformingPhysicianName | PN | 
| 00081070 | OperatorsName | PN | 
| 00081090 | ManufacturerModelName | LO | 
| 00180010 | ContrastBolusAgent | LO | 
| 00180015 | BodyPartExamined | CS | 
| 00180050 | SliceThickness | DS | 
| 00180088 | SpacingBetweenSlices | DS | 
| 00181000 | DeviceSerialNumber | LO | 
| 00181016 | SecondaryCaptureDeviceManufacturer | LO | 
| 00181018 | SecondaryCaptureDeviceManufacturerModelName | LO | 
| 00181019 | SecondaryCaptureDeviceSoftwareVersions | LO | 
| 00181020 | SoftwareVersions | LO | 
| 00181030 | ProtocolName | LO | 
| 00181050 | SpatialResolution | DS | 
| 00181200 | DateOfLastCalibration | DA | 
| 00181201 | TimeOfLastCalibration | TM | 
| 00185100 | PatientPosition | CS | 
| 0020000D | StudyInstanceUID | UI | 
| 0020000E | SeriesInstanceUID | UI | 
| 00200011 | SeriesNumber | IS | 
| 00200052 | FrameOfReferenceUID | UI | 
| 00200060 | 側位 | CS | 
| 00201209 | NumberOfSeriesRelatedInstances | IS | 
| 00540081 | NumberOfSlices | 美國 | 
| 00540101 | NumberOfTimeSlices | 美國 | 
| 00541000 | SeriesType | CS | 

#### 執行個體層級 (includefield=all)
<a name="dicomweb-includefield-all-instance"></a>

在執行個體層級， `includefield=all`會傳回完整的執行個體層級 DICOM 中繼資料。這包括存放在 HealthImaging 儲存體中執行個體中繼資料中的所有屬性。傳回該執行個體原始 DICOM 檔案中存在的每個 DICOM 標籤，像素資料屬性除外。

**Topics**
+ [HealthImaging 的 DICOMweb 搜尋 API APIs](#dicomweb-search-services)
+ [HealthImaging 支援的 DICOMweb 查詢類型](#dicomweb-query-types)
+ [在 QIDO-RS 查詢中使用 IncludeField](#dicomweb-includefield)
+ [在 HealthImaging 中搜尋 DICOM 檢查](dicomweb-search-studies.md)
+ [在 HealthImaging 中搜尋 DICOM 系列](dicomweb-search-series.md)
+ [在 HealthImaging 中搜尋 DICOM 執行個體](dicomweb-search-instances.md)
+ [在 HealthImaging 中搜尋檢查的 DICOM 執行個體](dicomweb-search-study-instances.md)
+ [在 HealthImaging 中搜尋所有 DICOM 系列](dicomweb-search-all-series.md)
+ [搜尋 HealthImaging 中的所有 DICOM 執行個體](dicomweb-search-all-instances.md)