Pesquisar recursos FHIR

Esta página explica as instruções básicas sobre como pesquisar recursos FHIR numa loja FHIR. A pesquisa de recursos FHIR é a principal forma de consultar e obter estatísticas a partir de dados FHIR.

Pode pesquisar recursos FHIR na Cloud Healthcare API das seguintes formas:

• Usando o visualizador FHIR na Google Cloud consola.
• Usar o método projects.locations.datasets.fhirStores.fhir.search. O método oferece as seguintes formas de pesquisar recursos FHIR:
  • GET pedidos
  • POST pedidos

Esta página resume muitas das funcionalidades de pesquisa usadas frequentemente, mas não é uma lista exaustiva das partes da especificação de pesquisa FHIR suportadas pela Cloud Healthcare API.

Usar o visualizador FHIR

O visualizador FHIR é uma página na Google Cloud consola que lhe permite pesquisar e ver o conteúdo dos recursos FHIR.

Para pesquisar recursos numa loja FHIR, conclua os seguintes passos:

1. Na Google Cloud consola, aceda à página Visualizador de FHIR.

   Aceder ao visualizador FHIR

2. Na lista pendente FHIR Store, selecione um conjunto de dados e, de seguida, selecione uma FHIR Store no conjunto de dados.

3. Para filtrar a lista de tipos de recursos, pesquise os tipos de recursos que quer apresentar:

   1. Clique no campo Tipo de recurso.

   2. Na lista pendente Propriedades apresentada, selecione Tipo de recurso.

   3. Introduza um tipo de recurso.

   4. Para pesquisar outro tipo de recurso, selecione OU na lista pendente Operadores apresentada e, em seguida, introduza outro tipo de recurso.

4. Na lista de tipos de recursos, selecione o tipo de recurso no qual quer pesquisar.

5. Na caixa de pesquisa da tabela de recursos apresentada, introduza o valor que quer pesquisar.

O visualizador FHIR apresenta os resultados da pesquisa numa tabela. Depois de selecionar um recurso, o visualizador FHIR apresenta o conteúdo do recurso.

Quando vê o conteúdo de um recurso, pode pesquisar dados no recurso.

Para pesquisar dados num recurso, siga estes passos:

1. Selecione um recurso.

2. No painel Visualizador FHIR, clique no separador Elementos.

3. Na caixa de pesquisa, introduza o valor que quer pesquisar.

Transferir dados binários em recursos FHIR

Para transferir os dados binários disponíveis associados a um recurso no visualizador FHIR, siga estes passos:

1. Selecione um recurso.

2. No painel Visualizador FHIR, clique no separador Elementos.

3. Se necessário, expanda os elementos para aceder ao elemento de recurso necessário.

4. Clique em Transferir ficheiro para transferir os dados disponíveis.

Criar e executar consultas de pesquisa avançada

Pode usar consultas de pesquisa avançada para pesquisar recursos FHIR específicos através da especificação de pesquisa FHIR.

Para criar uma consulta de pesquisa avançada, conclua os seguintes passos:

1. Na página do visualizador FHIR, clique no separador Pesquisar.

2. Para criar uma consulta de pesquisa, clique em Abrir criador de consultas.

   É apresentado o painel Seleção de consultas.

3. Na lista Selecionar um tipo de recurso FHIR, escolha o tipo de recurso FHIR que quer pesquisar.

4. Clique em Continuar.

5. Na lista Parâmetro, selecione o parâmetro que quer usar para pesquisar recursos.

6. Na lista Modificador, selecione o modificador a aplicar à consulta. A lista inclui apenas modificadores compatíveis com o tipo de dados do parâmetro selecionado.

   Esta é uma seleção opcional. Se não for selecionado nenhum modificador, é feita uma verificação de igualdade.

7. No campo Valor, introduza o valor do parâmetro de consulta.

8. Para adicionar mais do que um valor de parâmetro, clique em OU. Isto permite-lhe incluir vários valores do parâmetro de recurso na consulta de pesquisa.

   À medida que cria a consulta de pesquisa, esta é apresentada no painel Pré-visualização da consulta. Para ver o URL completo da consulta de pesquisa, clique em Mostrar caminho completo.

9. Para adicionar mais do que um parâmetro, clique em E.

10. Clique em Continuar.

11. Para incluir recursos referenciados pelos recursos devolvidos na sua consulta de pesquisa, escolha o parâmetro de recurso na lista pendente Parâmetros incluídos.

12. Para incluir recursos que referenciam os recursos devolvidos na sua consulta de pesquisa, escolha o parâmetro de recurso na lista pendente Parâmetros incluídos inversos.

13. Clique em Concluído para guardar a sua consulta de pesquisa.

    A consulta de pesquisa guardada é apresentada no campo FHIR search operation.

14. Para pesquisar recursos com a consulta, clique em Executar pesquisa.

    Os resultados da pesquisa são apresentados na lista Resultados da pesquisa. Para ver os detalhes de um recurso devolvido pela pesquisa, clique num recurso na lista.

15. Para guardar a consulta como um modelo de consulta, clique em Guardar modelo e escolha Guardar modelo ou Guardar modelo como. É-lhe pedido um nome e uma descrição para a consulta. Os parâmetros de consulta são guardados num modelo, mas todos os valores definidos são removidos.

Exemplo de consulta de pesquisa

O exemplo seguinte mostra uma consulta de pesquisa que procura recursos de reivindicação de um fornecedor de cuidados de saúde específico, Practitioner/12345, para o mês de agosto de 2021:

• Parâmetro: care-team
  • Valor: Practitioner/12345
• Operador: E
• Parâmetro: created
  • Prefixo: lt (lesser than)
  • Valor: 8/1/21, 12:00 AM
• Operador: E
• Parâmetro: created
  • Prefixo: gt (greater than)
  • Valor: 8/31/21, 11:59 PM

Esta opção é configurada da seguinte forma no painel Seleção de consultas e a consulta é pré-visualizada no painel Pré-visualização de consultas. A consulta é apresentada no campo operação de pesquisa FHIR.

Nota: o recurso CareTeam inclui uma referência a um recurso Practitioner que é definido incluindo o tipo de recurso, Practitioner, antes do ID exclusivo do recurso, 12345.

Editar consultas de pesquisa

Para editar uma consulta de pesquisa, faça uma das seguintes ações:

• Para editar a consulta no criador de consultas, clique em Abrir criador de consultas.
• Para editar manualmente a consulta, edite os valores dos parâmetros na caixa de texto.

Executar modelos de consultas

Para executar uma consulta a partir de um modelo guardado, conclua os seguintes passos:

1. Clique em Modelos guardados.

   É apresentado o separador Modelos de pesquisa do painel Seleção de consultas, que mostra todos os modelos de consultas guardados.

2. Selecione o modelo de consulta que quer executar e clique em Concluído.

   A consulta de pesquisa do modelo é apresentada no campo Operação de pesquisa FHIR sem valores.

3. Para definir os valores da sua consulta de pesquisa, edite os valores dos parâmetros no campo.

4. Clique em Executar pesquisa para pesquisar recursos com a consulta.

Partilhe recursos FHIR

Pode partilhar um link para as versões atuais ou do histórico de um recurso FHIR.

Autorizações necessárias para esta tarefa

Para realizar esta tarefa, tem de lhe ter sido concedidas as seguintes autorizações ou as seguintes funções de gestão de identidade e acesso (IAM):

Autorizações

• healthcare.fhirResources.get

Funções

• Leitor de recursos FHIR do Healthcare (roles/healthcare.fhirResourceReader)

Pode pedir ao seu administrador para lhe conceder estas funções de gestão de identidade e de acesso. Para ver instruções sobre como conceder funções, consulte os artigos Faça a gestão do acesso ou Controle o acesso aos recursos da Cloud Healthcare API. Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Nota: se criou um Google Cloud projeto para este guia, então, como criador do projeto, tem automaticamente a função do IAM Proprietário (roles/owner), que tem as autorizações. Não precisa de receber funções da IAM adicionais.

Consola

1. Na Google Cloud consola, aceda à página Visualizador de FHIR.

   Aceder ao visualizador FHIR

2. No menu FHIR store, selecione um conjunto de dados e, de seguida, selecione uma FHIR store no conjunto de dados.

3. Para filtrar a lista de tipos de recursos FHIR, pesquise os tipos de recursos que quer apresentar.

4. Clique no campo Tipo de recurso.

5. Na lista pendente Propriedades apresentada, selecione Tipo de recurso.

6. Introduza um tipo de recurso FHIR.

7. Na lista de tipos de recursos FHIR, selecione um tipo de recurso.

8. Na tabela de recursos FHIR apresentada, selecione ou pesquise um recurso.

9. No painel Visualizador FHIR, clique em Partilhar. É copiado automaticamente para a área de transferência um link para partilhar o recurso FHIR.

Usar o método search

Para pesquisar recursos FHIR com a API REST, use o método projects.locations.datasets.fhirStores.fhir.search. Pode chamar o método através de pedidos GET ou POST.

Usar o método search com GET

Os exemplos seguintes mostram como pesquisar recursos numa determinada FHIR store usando o método projects.locations.datasets.fhirStores.fhir.search com GET.

curl

Para pesquisar recursos numa loja FHIR, faça um pedido GET e especifique as seguintes informações:

• O nome do conjunto de dados
• O nome do FHIR store
• O tipo de recurso a pesquisar
• Uma string de consulta que contém as informações que está a pesquisar, conforme descrito na secção Construir uma consulta de pesquisa
• Uma chave de acesso

O exemplo seguinte mostra um pedido GET que usa curl para pesquisar todos os pacientes com o apelido "Smith".

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"

Se o pedido for bem-sucedido, o servidor devolve a resposta como um recurso FHIR Bundle no formato JSON. O Bundle.type é searchset e os resultados da pesquisa são entradas na matriz Bundle.entry. Neste exemplo, o pedido devolve um recurso de paciente único, incluindo os dados nesse recurso:

{
  "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

Para pesquisar recursos numa loja FHIR, faça um pedido GET e especifique as seguintes informações:

• O nome do conjunto de dados
• O nome do FHIR store
• O tipo de recurso a pesquisar
• Uma string de consulta que contém as informações que está a pesquisar, conforme descrito na secção Construir uma consulta de pesquisa
• Uma chave de acesso

O exemplo seguinte mostra um pedido GET que usa o Windows PowerShell para pesquisar todos os pacientes com o apelido "Smith".

$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

Se o pedido for bem-sucedido, o servidor devolve a resposta como um recurso FHIR Bundle no formato JSON. O Bundle.type é searchset e os resultados da pesquisa são entradas na matriz Bundle.entry. Neste exemplo, o pedido devolve um recurso de paciente único, incluindo os dados nesse recurso:

{
  "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

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.healthcare.v1.CloudHealthcare;
import com.google.api.services.healthcare.v1.CloudHealthcareScopes;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.net.URISyntaxException;
import java.util.Collections;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.HttpStatus;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpUriRequest;
import org.apache.http.client.methods.RequestBuilder;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;

public class FhirResourceSearchGet {
  private static final String FHIR_NAME =
      "projects/%s/locations/%s/datasets/%s/fhirStores/%s/fhir/%s";
  // The endpoint URL for the Healthcare API. Required for HttpClient.
  private static final String API_ENDPOINT = "https://healthcare.googleapis.com";
  private static final JsonFactory JSON_FACTORY = new GsonFactory();
  private static final NetHttpTransport HTTP_TRANSPORT = new NetHttpTransport();

  public static void fhirResourceSearchGet(String resourceName)
      throws IOException, URISyntaxException {
    // String resourceName =
    //    String.format(
    //        FHIR_NAME, "project-id", "region-id", "dataset-id", "fhir-store-id");
    // String resourceType = "Patient";

    // Instantiate the client, which will be used to interact with the service.
    HttpClient httpClient = HttpClients.createDefault();
    String uri = String.format("%s/v1/%s", API_ENDPOINT, resourceName);
    URIBuilder uriBuilder = new URIBuilder(uri).setParameter("access_token", getAccessToken());
    // To set additional parameters for search filtering, add them to the URIBuilder. For
    // example, to search for a Patient with the family name "Smith", specify the following:
    // uriBuilder.setParameter("family:exact", "Smith");

    HttpUriRequest request =
        RequestBuilder.get()
            .setUri(uriBuilder.build())
            .build();

    // Execute the request and process the results.
    HttpResponse response = httpClient.execute(request);
    HttpEntity responseEntity = response.getEntity();
    if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
      System.err.print(
          String.format(
              "Exception searching GET FHIR resources: %s\n", response.getStatusLine().toString()));
      responseEntity.writeTo(System.err);
      throw new RuntimeException();
    }
    System.out.println("FHIR resource GET search results: ");
    responseEntity.writeTo(System.out);
  }

  private static CloudHealthcare createClient() throws IOException {
    // Use Application Default Credentials (ADC) to authenticate the requests
    // For more information see https://cloud.google.com/docs/authentication/production
    GoogleCredentials credential =
        GoogleCredentials.getApplicationDefault()
            .createScoped(Collections.singleton(CloudHealthcareScopes.CLOUD_PLATFORM));
    // Create a HttpRequestInitializer, which will provide a baseline configuration to all requests.
    HttpRequestInitializer requestInitializer =
        request -> {
          new HttpCredentialsAdapter(credential).initialize(request);
          request.setConnectTimeout(60000); // 1 minute connect timeout
          request.setReadTimeout(60000); // 1 minute read timeout
        };
    // Build the client for interacting with the service.
    return new CloudHealthcare.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
        .setApplicationName("your-application-name")
        .build();
  }

  private static String getAccessToken() throws IOException {
    GoogleCredentials credential =
        GoogleCredentials.getApplicationDefault()
            .createScoped(Collections.singleton(CloudHealthcareScopes.CLOUD_PLATFORM));

    return credential.refreshAccessToken().getTokenValue();
  }
}

Node.js

// Import google-auth-library for authentication.
const {GoogleAuth} = require('google-auth-library');

const searchFhirResourcesGet = async () => {
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });
  // TODO(developer): uncomment these lines before running the sample
  // const cloudRegion = 'us-central1';
  // const projectId = 'adjective-noun-123';
  // const datasetId = 'my-dataset';
  // const fhirStoreId = 'my-fhir-store';
  // const resourceType = 'Patient';
  const url = `https://healthcare.googleapis.com/v1/projects/${projectId}/locations/${cloudRegion}/datasets/${datasetId}/fhirStores/${fhirStoreId}/fhir/${resourceType}`;

  const params = {};
  // Specify search filters in a params object. For example, to filter on a
  // Patient with the last name "Smith", set resourceType to "Patient" and
  // specify the following params:
  // params = {'family:exact' : 'Smith'};
  const client = await auth.getClient();
  const response = await client.request({url, method: 'GET', params});
  const resources = response.data.entry;
  console.log(`Resources found: ${resources.length}`);
  console.log(JSON.stringify(resources, null, 2));
};

searchFhirResourcesGet();

Python

def search_resources_get(
    project_id,
    location,
    dataset_id,
    fhir_store_id,
    resource_type,
):
    """
    Uses the searchResources GET method to search for resources in the given FHIR store.

    See https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/healthcare/api-client/v1/fhir
    before running the sample."""
    # Imports Python's built-in "os" module
    import os

    # Imports the google.auth.transport.requests transport
    from google.auth.transport import requests

    # Imports a module to allow authentication using a service account
    from google.oauth2 import service_account

    # Gets credentials from the environment.
    credentials = service_account.Credentials.from_service_account_file(
        os.environ["GOOGLE_APPLICATION_CREDENTIALS"]
    )
    scoped_credentials = credentials.with_scopes(
        ["https://www.googleapis.com/auth/cloud-platform"]
    )
    # Creates a requests Session object with the credentials.
    session = requests.AuthorizedSession(scoped_credentials)

    # URL to the Cloud Healthcare API endpoint and version
    base_url = "https://healthcare.googleapis.com/v1"

    # TODO(developer): Uncomment these lines and replace with your values.
    # project_id = 'my-project'  # replace with your GCP project ID
    # location = 'us-central1'  # replace with the parent dataset's location
    # dataset_id = 'my-dataset'  # replace with the parent dataset's ID
    # fhir_store_id = 'my-fhir-store' # replace with the FHIR store ID
    # resource_type = 'Patient'  # replace with the FHIR resource type
    url = f"{base_url}/projects/{project_id}/locations/{location}"

    resource_path = "{}/datasets/{}/fhirStores/{}/fhir/{}".format(
        url, dataset_id, fhir_store_id, resource_type
    )

    response = session.get(resource_path)
    response.raise_for_status()

    resources = response.json()

    print(
        "Using GET request, found a total of {} {} resources:".format(
            resources["total"], resource_type
        )
    )
    print(json.dumps(resources, indent=2))

    return resources

Usar o método search com POST

Os exemplos seguintes mostram como pesquisar recursos numa determinada FHIR store usando o método projects.locations.datasets.fhirStores.fhir.search com POST.

curl

Para pesquisar recursos numa loja FHIR, faça um pedido POST e especifique as seguintes informações:

• O nome do conjunto de dados
• O nome do FHIR store
• O tipo de recurso a pesquisar
• Uma string de consulta que contém as informações que está a pesquisar, conforme descrito na secção Construir uma consulta de pesquisa
• Uma chave de acesso

O exemplo seguinte mostra um pedido POST que usa curl para pesquisar todos os pacientes com o apelido "Smith".

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"

Se o pedido for bem-sucedido, o servidor devolve a resposta como um recurso FHIR Bundle no formato JSON. O Bundle.type é searchset e os resultados da pesquisa são entradas na matriz Bundle.entry. Neste exemplo, o pedido devolve um recurso de paciente único, incluindo os dados nesse recurso:

{
  "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

Para pesquisar recursos numa loja FHIR, faça um pedido POST e especifique as seguintes informações:

• O nome do conjunto de dados
• O nome do FHIR store
• O tipo de recurso a pesquisar
• Uma string de consulta que contém as informações que está a pesquisar, conforme descrito na secção Construir uma consulta de pesquisa
• Uma chave de acesso

O exemplo seguinte mostra um pedido POST que usa o Windows PowerShell para pesquisar todos os pacientes com o apelido "Smith".

$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

Se o pedido for bem-sucedido, o servidor devolve a resposta como um recurso FHIR Bundle no formato JSON. O Bundle.type é searchset e os resultados da pesquisa são entradas na matriz Bundle.entry. Neste exemplo, o pedido devolve um recurso de paciente único, incluindo os dados nesse recurso:

{
  "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

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.healthcare.v1.CloudHealthcare;
import com.google.api.services.healthcare.v1.CloudHealthcareScopes;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.net.URISyntaxException;
import java.util.Collections;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.HttpStatus;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpUriRequest;
import org.apache.http.client.methods.RequestBuilder;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClients;

public class FhirResourceSearchPost {
  private static final String FHIR_NAME =
      "projects/%s/locations/%s/datasets/%s/fhirStores/%s/fhir/%s";
  // The endpoint URL for the Healthcare API. Required for HttpClient.
  private static final String API_ENDPOINT = "https://healthcare.googleapis.com";
  private static final JsonFactory JSON_FACTORY = new GsonFactory();
  private static final NetHttpTransport HTTP_TRANSPORT = new NetHttpTransport();

  public static void fhirResourceSearchPost(String resourceName)
      throws IOException, URISyntaxException {
    // String resourceName =
    //    String.format(
    //        FHIR_NAME, "project-id", "region-id", "dataset-id", "store-id", "resource-type");

    // Instantiate the client, which will be used to interact with the service.
    HttpClient httpClient = HttpClients.createDefault();
    String uri = String.format("%s/v1/%s/_search", API_ENDPOINT, resourceName);
    URIBuilder uriBuilder = new URIBuilder(uri).setParameter("access_token", getAccessToken());
    // To set additional parameters for search filtering, add them to the URIBuilder. For
    // example, to search for a Patient with the family name "Smith", specify the following:
    // uriBuilder.setParameter("family:exact", "Smith");

    // Set a body otherwise HttpClient complains there is no Content-Length set.
    StringEntity requestEntity = new StringEntity("");

    HttpUriRequest request =
        RequestBuilder.post()
            .setUri(uriBuilder.build())
            .setEntity(requestEntity)
            .addHeader("Content-Type", "application/fhir+json")
            .addHeader("Accept-Charset", "utf-8")
            .addHeader("Accept", "application/fhir+json; charset=utf-8")
            .build();

    // Execute the request and process the results.
    HttpResponse response = httpClient.execute(request);
    HttpEntity responseEntity = response.getEntity();
    if (response.getStatusLine().getStatusCode() != HttpStatus.SC_OK) {
      System.err.print(
          String.format(
              "Exception searching POST FHIR resources: %s\n",
              response.getStatusLine().toString()));
      responseEntity.writeTo(System.err);
      throw new RuntimeException();
    }
    System.out.println("FHIR resource POST search results: ");
    responseEntity.writeTo(System.out);
  }

  private static CloudHealthcare createClient() throws IOException {
    // Use Application Default Credentials (ADC) to authenticate the requests
    // For more information see https://cloud.google.com/docs/authentication/production
    GoogleCredentials credential =
        GoogleCredentials.getApplicationDefault()
            .createScoped(Collections.singleton(CloudHealthcareScopes.CLOUD_PLATFORM));

    // Create a HttpRequestInitializer, which will provide a baseline configuration to all requests.
    HttpRequestInitializer requestInitializer =
        request -> {
          new HttpCredentialsAdapter(credential).initialize(request);
          request.setConnectTimeout(60000); // 1 minute connect timeout
          request.setReadTimeout(60000); // 1 minute read timeout
        };

    // Build the client for interacting with the service.
    return new CloudHealthcare.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
        .setApplicationName("your-application-name")
        .build();
  }

  private static String getAccessToken() throws IOException {
    GoogleCredentials credential =
        GoogleCredentials.getApplicationDefault()
            .createScoped(Collections.singleton(CloudHealthcareScopes.CLOUD_PLATFORM));

    return credential.refreshAccessToken().getTokenValue();
  }
}

Node.js

// Import google-auth-library for authentication.
const {GoogleAuth} = require('google-auth-library');

const searchFhirResourcesPost = async () => {
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
    // Set application/fhir+json header because this is a POST request.
    headers: {'Content-Type': 'application/fhir+json'},
  });
  // TODO(developer): uncomment these lines before running the sample
  // const cloudRegion = 'us-central1';
  // const projectId = 'adjective-noun-123';
  // const datasetId = 'my-dataset';
  // const fhirStoreId = 'my-fhir-store';
  // const resourceType = 'Patient';
  const url = `https://healthcare.googleapis.com/v1/projects/${projectId}/locations/${cloudRegion}/datasets/${datasetId}/fhirStores/${fhirStoreId}/fhir/${resourceType}/_search`;

  const params = {};
  // Specify search filters in a params object. For example, to filter on a
  // Patient with the last name "Smith", set resourceType to "Patient" and
  // specify the following params:
  // params = {'family:exact' : 'Smith'};
  const client = await auth.getClient();
  const response = await client.request({url, method: 'POST', params});
  const resources = response.data.entry;
  console.log(`Resources found: ${resources.length}`);
  console.log(JSON.stringify(resources, null, 2));
};

searchFhirResourcesPost();

Python

def search_resources_post(project_id, location, dataset_id, fhir_store_id):
    """
    Searches for resources in the given FHIR store. Uses the
    _search POST method and a query string containing the
    information to search for. In this sample, the search criteria is
    'family:exact=Smith' on a Patient resource.

    See https://github.com/GoogleCloudPlatform/python-docs-samples/tree/main/healthcare/api-client/v1/fhir
    before running the sample."""
    # Imports Python's built-in "os" module
    import os

    # Imports the google.auth.transport.requests transport
    from google.auth.transport import requests

    # Imports a module to allow authentication using a service account
    from google.oauth2 import service_account

    # Gets credentials from the environment.
    credentials = service_account.Credentials.from_service_account_file(
        os.environ["GOOGLE_APPLICATION_CREDENTIALS"]
    )
    scoped_credentials = credentials.with_scopes(
        ["https://www.googleapis.com/auth/cloud-platform"]
    )
    # Creates a requests Session object with the credentials.
    session = requests.AuthorizedSession(scoped_credentials)

    # URL to the Cloud Healthcare API endpoint and version
    base_url = "https://healthcare.googleapis.com/v1"

    # TODO(developer): Uncomment these lines and replace with your values.
    # project_id = 'my-project'  # replace with your GCP project ID
    # location = 'us-central1'  # replace with the parent dataset's location
    # dataset_id = 'my-dataset'  # replace with the parent dataset's ID
    # fhir_store_id = 'my-fhir-store' # replace with the FHIR store ID
    url = f"{base_url}/projects/{project_id}/locations/{location}"

    fhir_store_path = "{}/datasets/{}/fhirStores/{}/fhir".format(
        url, dataset_id, fhir_store_id
    )

    resource_path = f"{fhir_store_path}/Patient/_search?family:exact=Smith"

    # Sets required application/fhir+json header on the request
    headers = {"Content-Type": "application/fhir+json;charset=utf-8"}

    response = session.post(resource_path, headers=headers)
    response.raise_for_status()

    resources = response.json()
    print(
        "Using POST request, found a total of {} Patient resources:".format(
            resources["total"]
        )
    )

    print(json.dumps(resources, indent=2))

    return resources

Construir uma consulta de pesquisa

A string de consulta é uma série de pares name=value codificados no formato de URL. Uma pesquisa combina todos os pares com um AND lógico. Cada valor pode ser uma lista de valores separados por vírgulas, que são tratados como um OR lógico desses valores. Por exemplo, Patient?key1=value1&key2=value2,value3 é uma pesquisa de recursos para pacientes com os seguintes critérios:

(key1 = value1) AND (key2 = value2 OR key2 = value3)

Não existe sintaxe para executar um OR de dois pares name=value.

Cada tipo de recurso FHIR define os seus próprios parâmetros de pesquisa em cada versão do FHIR. Os parâmetros disponíveis estão documentados na especificação FHIR para cada recurso. Para ver um exemplo, consulte FHIR R4 Patient. Pode obter os parâmetros de forma programática através da declaração de capacidade. A Cloud Healthcare API suporta a maioria dos parâmetros de pesquisa. Pode encontrar exclusões através da declaração de capacidade ou da declaração de conformidade com a FHIR.

Paginação e ordenação

O número de recursos devolvidos em cada página dos resultados da pesquisa FHIR depende dos seguintes fatores:

• O parâmetro _count. Controla o número máximo de recursos devolvidos pelo método de pesquisa. Por exemplo, _count=10 devolve, no máximo, 10 recursos correspondentes à consulta. A predefinição é 100 e o valor máximo permitido é 1000.
• O tamanho dos dados de resposta. Uma página de resultados da pesquisa pode devolver menos recursos do que o valor especificado no parâmetro _count se o tamanho da resposta for grande.

Se uma pesquisa devolver mais recursos do que o número de recursos que cabem numa página, a resposta inclui um URL de paginação no campo Bundle.link. Podem ser devolvidos vários valores neste campo; o valor com Bundle.link.relation = next indica que pode usar o Bundle.link.url correspondente para obter a página seguinte.

O valor de Bundle.total indica o número total de recursos correspondentes. Este valor é exato se os resultados couberem inteiramente numa página, mas torna-se uma estimativa aproximada à medida que o número de resultados aumenta e ultrapassa uma página. Pode obter um total exato para uma pesquisa que corresponda a muitos resultados seguindo repetidamente os links de paginação até esgotar os resultados.

Para mais informações sobre a paginação e os totais de pesquisa, consulte o artigo Implementar a paginação e os totais de pesquisa com a pesquisa FHIR.

Pode ordenar os resultados através do parâmetro _sort, que aceita uma lista separada por vírgulas de nomes de parâmetros de pesquisa por ordem de prioridade. Pode usar um prefixo - para indicar a ordem decrescente. Por exemplo, a seguinte consulta ordena por estado ascendente, desempata por data descendente e desempata todos os restantes empates por categoria ascendente:

_sort=status,-date,category

Nota: uma loja FHIR configurada para usar a versão DSTU2 usa uma sintaxe _sort diferente que estava presente nessa versão da especificação. Cada instância de _sort usa um parâmetro de pesquisa e um modificador opcional de :asc ou :desc. Por exemplo, no DSTU2, para realizar a mesma ordem de ordenação que no exemplo anterior, use: _sort=status&_sort:desc=date&_sort=category.

_sort só é suportado para parâmetros de pesquisa do tipo number, data, string, token e quantity. Para ordenar usando outros tipos de parâmetros de pesquisa (por exemplo, reference), use pesquisas personalizadas FHIR para criar, por exemplo, um parâmetro de pesquisa string no campo reference.

Atraso na indexação

Os recursos FHIR são indexados de forma assíncrona, pelo que pode haver um ligeiro atraso entre o momento em que um recurso é criado ou alterado e o momento em que a alteração se reflete nos resultados da pesquisa. A única exceção são os dados do identificador de recursos, que são indexados de forma síncrona como um índice especial. Como resultado, a pesquisa com o identificador do recurso não está sujeita a atrasos na indexação. Para usar o índice síncrono especial, o termo de pesquisa do identificador deve estar no padrão identifier=[system]|[value] ou identifier=[value], e pode usar qualquer um dos seguintes parâmetros de resultados da pesquisa:

• _count
• _include
• _revinclude
• _summary
• _elements

Se a sua consulta contiver outros parâmetros de pesquisa, é usado o índice assíncrono padrão. Tenha em atenção que a pesquisa no índice especial está otimizada para resolver um pequeno número de correspondências. A pesquisa não está otimizada se os critérios de pesquisa de identificadores corresponderem a um grande número (ou seja,mais de 2000) de recursos. Para uma consulta de pesquisa que corresponda a um grande número de recursos, pode evitar usar o índice síncrono especial incluindo um parâmetro _sort adicional na sua consulta. Use _sort=-_lastUpdated se quiser manter a ordem de ordenação predefinida.

A pesquisar em todos os tipos de recursos

Determinados parâmetros de pesquisa, apresentados com um sublinhado inicial, como _id, aplicam-se a todos os tipos de recursos. Estes parâmetros de todos os recursos estão listados na especificação FHIR para o tipo de recurso.

Quando usa estes parâmetros de pesquisa, pode fazer uma pesquisa em vários tipos de recursos omitindo o tipo de recurso do caminho do pedido. Por exemplo, usar GET .../fhir?_id=1234 em vez de GET .../fhir/Patient?_id=1234 pesquisa em todos os recursos FHIR em vez de apenas num recurso Patient. Pode usar o parâmetro especial _type com este tipo de pedido para limitar os resultados a uma lista separada por vírgulas de tipos de recursos. Por exemplo, a seguinte consulta só devolve resultados correspondentes para os recursos Observation e Condition:

GET .../fhir?_tag=active&_type=Observation,Condition

Tipos de dados

Cada parâmetro de pesquisa definido pela FHIR tem um tipo de dados, que inclui tipos primitivos, como os seguintes:

• String
• Número
• Data

Os tipos de dados também incluem os seguintes tipos complexos:

• Símbolo
• Referência
• Quantidade

Cada tipo de dados tem a sua própria sintaxe para especificar valores. Cada tipo de dados suporta modificadores que alteram a forma como a pesquisa é realizada.

As secções seguintes mostram como usar tipos de dados. Para mais detalhes sobre tipos de dados adicionais, sintaxes de valores e modificadores, consulte as Funcionalidades de pesquisa FHIR avançadas.

Número

Pesquisas em valores de números inteiros ou de vírgula flutuante. Para alterar o comparador, adicione um dos seguintes modificadores ao valor:

• ne
• lt
• le
• gt
• ge

Por exemplo, use [parameter]=100 para igualdade ou use [parameter]=ge100 para superior ou igual a 100.

Data

Pesquisas sobre qualquer tipo de data, hora ou período. O formato do parâmetro de data é o seguinte:

yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]

Aplicam-se os mesmos modificadores de prefixo usados para o número.

String

A predefinição é uma pesquisa de prefixo que não é sensível a maiúsculas/minúsculas, acentos ou outras marcas diacríticas.

Nota: os carateres de pontuação dividem uma pesquisa em várias palavras e os próprios carateres de pontuação são ignorados.

Símbolo

Pesquisas de uma correspondência exata de uma string de um "código". Pode restringir a pesquisa ao URI de um "sistema" que indica o valor a partir do qual o código é retirado através do seguinte formato:

[parameter]=[system]|[code]

Por exemplo, a seguinte pesquisa corresponde a um código de 10738-3, mas apenas quando qualificado como um valor de um sistema de codificação com o URI especificado:

code=http://hl7.org/fhir/ValueSet/observation-codes|10738-3

Quantidade

Procura um valor numérico usando os mesmos modificadores de prefixo que number. Pode qualificar a pesquisa com um sistema e um código específicos que indicam as unidades do valor no seguinte formato:

[parameter]=[prefix][number]|[system]|[code]

Por exemplo, a seguinte consulta pesquisa valores de quantidade inferiores a 9,1 que tenham o sistema de unidades e o código especificados:

value-quantity=lt9.1|http://unitsofmeasure.org|mg

Referência

Pesquisa referências entre recursos. Pode usar as seguintes consultas para referências a recursos num FHIR store:

• [parameter]=[id]
• [parameter]=[type]/[id]

Pode usar [parameter]=[url] para especificar referências por URL que podem estar fora da loja FHIR.

Processamento de parâmetros de pesquisa

Por predefinição, o método de pesquisa aplica o processamento "leniente", que ignora os parâmetros que a pesquisa não reconhece. O método de pesquisa executa a pesquisa usando quaisquer parâmetros restantes no pedido, o que pode devolver mais recursos do que o esperado.

A resposta inclui o seguinte:

• Um valor em Bundle.link com um valor de Bundle.link.relation = self
• Um Bundle.link.url de um URL que contém apenas os parâmetros que foram aplicados com êxito à pesquisa. Pode inspecionar este valor para determinar se algum parâmetro foi ignorado.

Pode definir o cabeçalho HTTP do pedido como Prefer: handling=strict num pedido de pesquisa. A definição do cabeçalho faz com que o armazenamento FHIR devolva um erro em qualquer parâmetro não reconhecido.

Nota: definir a opção da loja FHIR defaultSearchHandlingStrict altera esta predefinição para strict para todos os pedidos de pesquisa, a menos que um pedido individual use o cabeçalho HTTP Prefer: handling=lenient para escolher a opção tolerante.