このページでは、projects.locations.datasets.fhirStores.fhir.search
メソッドを使用して特定の FHIR ストア内のリソースを検索する方法について説明します。GET
または POST
リクエストを使用して、さまざまな方法でメソッドを呼び出すことができます。FHIR 検索の仕様には、幅広いクエリ機能が含まれています。このページでは、頻繁に使用される機能の多くについて概要を説明しますが、Cloud Healthcare API でサポートされている検索仕様のすべての部分を示しているわけではありません。
GET
で search
メソッドを使用する
次のサンプルは、GET
で projects.locations.datasets.fhirStores.fhir.search
メソッドを使用して、特定の FHIR ストア内のリソースを検索する方法を示しています。
curl
FHIR ストア内のリソースを検索するには、GET
リクエストを行い、次の情報を指定します。
- データセットの名前
- FHIR ストアの名前
- 検索するリソースのタイプ
- 検索する情報が含まれるクエリ文字列。検索クエリの作成をご覧ください。
- アクセス トークン
次のサンプルは、curl
を使用して姓が「Smith」のすべての患者を検索する GET
リクエストを示しています。
curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient?family:exact=Smith"
リクエストが成功すると、サーバーはレスポンスを JSON 形式の FHIR Bundle
として返します。Bundle.type
は searchset
で、検索結果は Bundle.entry
配列のエントリです。この例では、リクエストはそのリソース内のデータを含む単一の患者リソースを返します。
{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
PowerShell
FHIR ストア内のリソースを検索するには、GET
リクエストを行い、次の情報を指定します。
- データセットの名前
- FHIR ストアの名前
- 検索するリソースのタイプ
- 検索する情報が含まれるクエリ文字列。検索クエリの作成をご覧ください。
- アクセス トークン
次のサンプルは、Windows PowerShell を使用して姓が「Smith」のすべての患者を検索する GET
リクエストを示しています。
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Get ` -Headers $headers ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/RESOURCE_TYPE?family:exact=Smith" | ConvertTo-Json
リクエストが成功すると、サーバーはレスポンスを JSON 形式の FHIR Bundle
として返します。Bundle.type
は searchset
で、検索結果は Bundle.entry
配列のエントリです。この例では、リクエストはそのリソース内のデータを含む単一の患者リソースを返します。
{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
Java
Node.js
Python
POST
で search
メソッドを使用する
次のサンプルは、POST
で projects.locations.datasets.fhirStores.fhir.search
メソッドを使用して、特定の FHIR ストア内のリソースを検索する方法を示しています。
curl
FHIR ストア内のリソースを検索するには、POST
リクエストを行い、次の情報を指定します。
- データセットの名前
- FHIR ストアの名前
- 検索するリソースのタイプ
- 検索する情報が含まれるクエリ文字列。検索クエリの作成をご覧ください。
- アクセス トークン
次のサンプルは、curl
を使用して姓が「Smith」のすべての患者を検索する POST
リクエストを示しています。
curl -X POST \ --data "" \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/fhir+json; charset=utf-8" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/_search?family:exact=Smith"
リクエストが成功すると、サーバーはレスポンスを JSON 形式の FHIR Bundle
として返します。Bundle.type
は searchset
で、検索結果は Bundle.entry
配列のエントリです。この例では、リクエストはそのリソース内のデータを含む単一の患者リソースを返します。
{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
PowerShell
FHIR ストア内のリソースを検索するには、POST
リクエストを行い、次の情報を指定します。
- データセットの名前
- FHIR ストアの名前
- 検索するリソースのタイプ
- 検索する情報が含まれるクエリ文字列。検索クエリの作成をご覧ください。
- アクセス トークン
次のサンプルは、Windows PowerShell を使用して姓が「Smith」のすべての患者を検索する POST
リクエストを示しています。
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json; charset=utf-8" ` -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/_search?family:exact=Smith" | ConvertTo-Json
リクエストが成功すると、サーバーはレスポンスを JSON 形式の FHIR Bundle
として返します。Bundle.type
は searchset
で、検索結果は Bundle.entry
配列のエントリです。この例では、リクエストはそのリソース内のデータを含む単一の患者リソースを返します。
{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
Java
Node.js
Python
検索クエリの作成
クエリ文字列は、URL 形式でエンコードされた一連の name=value
ペアです。検索では、すべてのペアが論理 AND
と結合されます。各値は、値の論理 OR
として扱われる値のカンマ区切りリストにすることができます。例:
Patient?key1=value1&key2=value2,value3
は、条件による Patient
リソースの検索です。
(key1 = value1) AND (key2 = value2 OR key2 = value3)
名前と値の 2 つのペアの OR を実行する構文はありません。
FHIR リソースタイプでは、FHIR の各バージョンの独自の検索パラメータを定義します。使用可能なパラメータは、各リソースの FHIR 仕様に記載されています(たとえば、FHIR R4 Patient)。これは、機能ステートメントでプログラムによって取得できます。 Cloud Healthcare API では、ほとんどの検索パラメータがサポートされています。除外される検索パラメータについては、機能ステートメントまたは FHIR 適合性宣言で確認できます。
ページ分けと並べ替え
検索メソッドから返されるリソースの最大数は、_count
パラメータによって制御されます。たとえば、_count=10
はクエリに一致するリソースを最大 10 個返します。デフォルトは 100 で、許容最大値は 1000 です。
検索で 1 ページに収まらないほど多くのリソースが見つかった場合は、レスポンスの Bundle.link
フィールドにページ設定 URL が含まれます。このフィールドには複数の値が返される場合があります。Bundle.link.relation = next
の値は、対応する Bundle.link.url
を使用して次のページを取得できることを示します。Bundle.total
の値は、一致するリソースの合計数を示します。この値は、結果が 1 ページに完全に収まる場合には正確に表示されますが、結果の数が 1 ページよりも大幅に多い場合には概算的な推計値として示されます。多数の結果に一致する検索の正確な合計は、結果がなくなるまで繰り返しページ分けリンクをたどることでのみ取得できます。
結果は、_sort
パラメータを使用して並べ替えることができます。このパラメータは、優先順位で並べた検索パラメータのカンマ区切りリストを受け入れ、オプションで降順での並べ替えを示す -
接頭辞を付すことができます。例:
_sort=status,-date,category
ステータスの昇順で並べ替えられ、日付の降順、カテゴリの昇順は解除されます。
インデックスの遅延
FHIR リソースは非同期でインデックスに登録されるため、リソースが作成または変更されてから変更が検索結果に反映されるまでにわずかな遅延が発生する場合があります。
すべてのリソースタイプでの検索
_id
のように先頭に付されたアンダースコアによって識別される検索パラメータは、すべてのリソースタイプに適用されます。これらすべてのリソース パラメータは、Resource
タイプの FHIR の仕様に記載されています。
こうした検索パラメータを使用すると、リクエストパスでリソースタイプを省略して、複数のリソースタイプにまたがって検索できます。たとえば、GET .../fhir/Patient?_id=1234
の代わりに GET .../fhir?_id=1234
を使用すると、Patient のみではなく、すべてのリソースを対象として検索されます。このタイプのリクエストで特別なパラメータ _type
を使用すると、リソースタイプのカンマ区切りリストに結果を制限できます。次に例を示します。
GET .../fhir?_tag=active&_type=Observation,Condition
Observation
と Condition
のリソースに一致する結果のみが返されます。
データ型
FHIR によって定義された各検索パラメータには、プリミティブ型(文字列、数値、日付など)と複雑な型(トークン、参照、数量など)などのデータ型があります。各データ型には値を指定する独自の構文があり、検索の実行方法を変更する修飾子がサポートされます。
データ型の使用方法に関するシンプルな例を次に示します。
- Number は整数値または浮動小数点値を検索します。値の先頭に
ne, lt, le, gt, ge
などの修飾子を付けると、比較子を変更できます(例: 等式の場合は[parameter]=100
、100 以上の場合は[parameter]=ge100
)。 - Date では、任意の日付、時刻、または期間を検索します。日付パラメータの形式は
yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]
で、数値に使用されているのと同じ接頭辞修飾子もここに適用されます。 - String のデフォルト設定は、大文字と小文字、アクセント記号、その他の発音区別符号を区別しない接頭辞検索です。
- Token は、「コード」と完全に一致する文字列を検索します。必要に応じて、「システム」の URI を範囲とし、
[parameter]=[system]|[code]
の形式を使用したコードの取得元である値のセットを示します。たとえば、code=http://hl7.org/fhir/ValueSet/observation-codes|10738-3
は、指定された URI のコーディング システムから取得した値として修飾された場合にのみ、コード 10738-3 に一致します。 - Quantity は、数値と同じ接頭辞修飾子を使用して数値を検索します。必要に応じて、
[parameter]=[prefix][number]|[system]|[code]
形式の値の単位を示す特定のシステムとコードで修飾されます。 たとえば、value-quantity=lt9.1|http://unitsofmeasure.org|mg
は、指定した単位系とコードを持つ 9.1 未満の数量値を検索します。 - Reference は、リソース間の参照を検索します。FHIR ストア内のリソースへの参照の場合は
[parameter]=[id]
または[parameter]=[type]/[id]
、FHIR ストアの外部に存在する可能性がある URL による参照の場合は[parameter]=[url]
で指定できます。
その他のデータ型、値の構文、修飾子の詳細については、高度な FHIR 検索機能をご覧ください。
検索パラメータの処理
デフォルトでは、検索メソッドは「lenient」処理を適用します。これにより、認識されないパラメータは無視され、リクエスト内の残りのパラメータを使用して検索を実行し、想定を上回るリソースを返す場合があります。
レスポンスには、値が Bundle.link.relation = self
の Bundle.link
値と、検索に正常に適用されたパラメータのみが含まれる URL の Bundle.link.url
が含まれます。この値を調べると、パラメータが無視されたかどうかを判断できます。
または、検索リクエストに HTTP ヘッダー Prefer: handling=strict
を設定すると、認識できないパラメータに対して FHIR ストアからエラーが返されます。