Declaração de conformidade DICOM

Os armazenamentos DICOM na API Cloud Healthcare são compatíveis com um subconjunto dos serviços da Web RESTful especificados no padrão DICOM PS3.18 - Serviços da Web (normalmente chamado de DICOMweb). Especificamente, eles são compatíveis com os Serviços e recursos de estudos (anteriormente chamados de serviços WADO-RS, STOW-RS e QIDO-RS).

Além disso, a API Cloud Healthcare é compatível com um serviço da Web próprio para excluir instâncias DICOM.

A API Cloud Healthcare não é compatível com o serviço de URI, o serviço de lista de trabalho, o serviço de instância não relacionada a pacientes ou qualquer um dos recursos Transações.

Recuperar transação

A Recuperação de transação é um serviço da Web RESTful para recuperar dados de imagem DICOM.

A transação de recuperação é compatível com a recuperação dos seguintes recursos:

  • Recursos DICOM:
    • Estudo
    • Série
    • Instance
    • Frames
    • Dados em massa
  • Recursos de metadados
    • Estudo
    • Série
    • Instance
  • Recursos renderizados
    • Instance
    • Frames

Ele não é compatível com recursos de miniatura.

Para mais detalhes, consulte Cotas e limites para esses métodos.

Estudo, série e instâncias do DICOM

Os seguintes cabeçalho Accept são aceitos:

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 (padrão)
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.90
  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.4.91
  • multipart/related; type="application/dicom"; transfer-syntax=*

Instâncias DICOM

Além dos cabeçalhos Accept acima, o RetrieveInstance é compatível com tipos de conteúdo de parte única por conveniência:

  • application/dicom; transfer-syntax=1.2.840.10008.1.2.1
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.90
  • application/dicom; transfer-syntax=1.2.840.10008.1.2.4.91
  • application/dicom; transfer-syntax=*

Isso não faz parte do padrão DICOMweb oficial.

Frames DICOM

Os seguintes cabeçalho Accept são aceitos:

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (padrão)
  • multipart/related; type="application/octet-stream"; transfer-syntax=*
  • multipart/related; type="image/jpeg"; transfer-syntax=1.2.840.10008.1.2.4.50
  • multipart/related; type="image/png"

Uma sintaxe de transferência de * permite que o usuário solicite que nenhuma transcodificação seja feita. Portanto, a sintaxe de transferência do arquivo enviado será usada. Para application/octet-stream, os dados em massa serão retornados em qualquer formato exibido no arquivo DICOM enviado.

Recursos renderizados

Os seguintes cabeçalho Accept são aceitos:

  • image/jpeg (padrão)
  • image/png

Somente a recuperação de recursos de frame ou instância é compatível.

Nenhum parâmetro de URL é suportado.

Recursos de metadados

Os seguintes cabeçalho Accept são aceitos:

  • application/dicom+json (padrão)
  • multipart/related; type=application/dicom+xml

As tags codificadas como elementos InlineBinary são codificadas usando a ordem de bytes little-endian, porque o parâmetro de sintaxe de transferência não é aceito em endpoints que solicitam recursos de metadados.

Por padrão, RetrieveMetadata não retorna nenhum atributo que tenha uma representação de valor DICOM de OB, OW ou UN. Para retornar BulkDataURIs para tags correspondentes a prévia Definição de Bulkdata; use o método Preview version.

As tags de sequência DICOM que contêm mais de aproximadamente 1 MiB de dados não serão retornadas nos recursos de metadados. Essa limitação se aplica somente aos recursos de metadados. Os recursos DICOM ainda conterão essas tags.

Recursos de dados em massa (pré-lançamento)

Os seguintes cabeçalho Accept são aceitos:

  • multipart/related; type="application/octet-stream"; transfer-syntax=* (padrão)
  • application/octet-stream; transfer-syntax=*

Sintaxes de transferência compatíveis para transcodificação

Os cabeçalhos Accept acima descrevem quais tipos de mídia e sintaxes de transferência você pode solicitar da API, mas isso nem sempre é possível, dependendo da sintaxe de transferência do arquivo original que foi enviado. Especificamente, a transcodificação só é possível a partir das seguintes sintaxes de transferência:

  • 1.2.840.10008.1.2 (Little Endian Implícita)
  • 1.2.840.10008.1.2.1 (Little Endian Explícita)
  • 1.2.840.10008.1.2.2 (Big Endian VR explícita)
  • 1.2.840.10008.1.2.4.50 (Processo básico de JPEG 1)
  • 1.2.840.10008.1.2.4.57 (JPEG sem perdas)
  • 1.2.840.10008.1.2.4.70 (Valor de seleção sem perdas de JPEG 1)
  • 1.2.840.10008.1.2.4.90 (somente JPEG 2000 sem perdas)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (RLE sem perdas)

Se o arquivo original tiver uma sintaxe de transferência diferente da exibida na lista acima e você solicitar a transcodificação para outro formato, um erro será retornado.

A API Cloud Healthcare não pode transcodificar imagens não monocromáticas com profundidade de bits maior que 8 para JPEG. Além disso, as imagens com um valor de 1 em Bits Alocados (0028, 0100) são armazenados em dados de pixels de flutuação (7FE0,0008), dados de pixel de ponto flutuante (7FE0,0009) as tags só podem ser transcodificadas entre formatos nativos.

Para desativar a transcodificação e recuperar qualquer arquivo da API, defina transfer-syntax=* no cabeçalho Accept.

Códigos de status

País Significado
200 (OK) O payload da resposta contém representações para todos os recursos de destino.
400 (Solicitação inválida) A solicitação era inválida (por exemplo, parâmetros de consulta ou cabeçalhos inválidos) para os recursos de destino especificados (por exemplo, dados de pixel ausentes).
401 (Não autorizado) Faltam credenciais de autenticação na solicitação.
403 (Permissão recusada) O usuário autenticado não tem acesso a esse recurso (ou o recurso não existe).
406 (Não aceitável) O servidor não suporta nenhum dos tipos de mídia aceitáveis.
429 (Há muitas solicitações) O cliente está excedendo a cota.
503 (Serviço não disponível) O servidor não está disponível no momento ou a solicitação excedeu o prazo.

Transação de armazenamento

A Transação de armazenamento é um serviço da Web RESTful para armazenar dados de imagem DICOM.

A transação de armazenamento aceita arquivos binários DICOM da Parte 10 diretamente ou aceita a divisão de um arquivo DICOM em metadados (representados em JSON) e dados em massa. Essas duas versões têm semânticas diferentes descritas nas seções a seguir.

Para mais detalhes, consulte Cotas e limites para esse método.

Arquivos binários DICOM parte 10

Os seguintes Content-Types são compatíveis:

  • multipart/related; type=application/dicom
  • application/dicom

Nenhuma restrição ou substituição de atributos é feita pelo servidor.

Esta versão aceita todas as sintaxes de transferência e classes SOP. Apenas a validação mínima do arquivo DICOM é feita para extrair alguns atributos de metadados principais.

Por conveniência, a transação de armazenamento também aceita uma solicitação HTTP de parte com uma instância DICOM com o tipo de conteúdo application/dicom. Isso não faz parte do padrão DICOMweb oficial.

Consulte Armazenar uma instância DICOM para conferir o guia de instruções associado.

Metadados JSON e solicitações de dados em massa

Ao armazenar instâncias usando metadados JSON e dados em massa, a primeira parte precisa consistir em uma matriz JSON de instâncias DICOM.

A primeira parte precisa ter um Content-Type de application/dicom+json; transfer-syntax=TransferSyntaxUID, em que TransferSyntaxUID é a sintaxe de transferência usada para codificar dados binários em objetos InlineBinary. Se nenhum objeto InlineBinary estiver presente nos metadados, o parâmetro transfer-syntax poderá ser omitido.

Os seguintes elementos DICOM precisam estar presentes em todas as instâncias nos metadados JSON:

  • SpecificCharacterSet
  • TransferSyntaxUID
  • SOPClassUID
  • StudyInstanceUID
  • SeriesInstanceUID
  • SOPInstanceUID

É preciso definir o elemento SpecificCharacterSet como ISO_IR 192, e os metadados JSON precisam ser codificados em UTF-8 unicode. O TransferSyntaxUID pode ser definido como qualquer sintaxe de transferência válida, exceto como as seguintes sintaxes de transferência não compatíveis:

  • 1.2.840.10008.1.2.2 (Big Endian VR explícita)
  • 1.2.840.10008.1.2.1.99 (Little Endian VR explícita com Deflate)

Nos metadados JSON, o usuário pode especificar vários BulkDataURIs para tags DICOM com VRs de OB, OW ou UN. Esses BulkDataURIs indicam que os dados binários da tag que contém o URI serão enviados na parte seguinte, que tem o cabeçalho Content-Location definido como o BulkDataURI.

Cada instância nos metadados JSON pode ter no máximo um BulkDataURI. Não deve haver nenhum BulkDataURIs duplicado nos metadados JSON. Os dados em massa da imagem compactada só podem ser enviados para a tag PixelData e, quando enviados, a sintaxe de transferência especificada na parte de dados em massa precisa corresponder ao valor do elemento TransferSyntaxUID da instância.

Os seguintes Content-Types são compatíveis com partes de dados em massa:

  • application/octet-stream
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.70
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.4.50
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​51
  • image/jpeg; transfer-syntax=1.2.840.10008.1.2.​4.​57
  • image/x-dicom-rle; transfer-syntax=1.2.840.10008.1.2.5
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.​4.​80
  • image/x-jls; transfer-syntax=1.2.840.10008.1.2.4.81
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.90
  • image/jp2; transfer-syntax=1.2.840.10008.1.2.4.91
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.92
  • image/jpx; transfer-syntax=1.2.840.10008.1.2.4.93

Um método alternativo para especificar dados binários é codificá-los como uma string codificada em base64 InlineBinary. Isso é compatível com todas as tags, exceto o PixelData, que precisa ser enviado como uma parte de dados em massa. Quando objetos InlineBinary são usados nos metadados JSON, a sintaxe de transferência usada para codificação deve ser especificada no Content-Type da parte de metadados JSON.

O servidor não deriva atributos de macro de descrição de pixel de imagem.

Consulte Criar instâncias DICOM a partir de metadados JSON e arquivos JPEG para consultar o guia de instruções associado.

Resposta

Em um erro, será retornada uma tag FailureDetail (0009, 0097) (para respostas XML) ou uma tag FailureDetailJSON (0009,1097) (para respostas JSON). A tag FailureDetail fornece uma descrição legível do erro.

Se uma instância DICOM tiver a mesma tupla <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID> que outra instância já na loja DICOM, um erro Falha no processamento será retornado com uma tag FailureDetail "já existente".

A resposta pode estar no formato JSON ou XML, que pode ser controlada por meio dos seguintes valores de cabeçalho Accept:

  • application/dicom+xml (padrão)
  • application/dicom+json

Códigos de status

País Significado
200 (OK) O recurso foi armazenado.
400 (Solicitação inválida) A solicitação era inválida (por exemplo, tipo de mídia ou sintaxe de transferência não suportado).
401 (Não autorizado) Faltam credenciais de autenticação na solicitação.
403 (Permissão recusada) O usuário autenticado não tem acesso a esse recurso (ou o recurso não existe).
406 (Não aceitável) O servidor não suporta nenhum dos tipos de mídia aceitáveis.
409 (Conflito) Pelo menos um recurso não foi armazenado (por exemplo, arquivo DICOM inválido). Verifique a tag FailureDetail no corpo da resposta para mais informações.
429 (Há muitas solicitações) O cliente está excedendo a cota.
503 (Serviço não disponível) O servidor não está disponível no momento ou a solicitação excedeu o prazo.

Pesquisar transação

A transação de pesquisa é um serviço da Web RESTful para consultar metadados de imagem DICOM.

A API Cloud Healthcare é compatível com a pesquisa de estudos, séries e instâncias.

Parâmetros de pesquisa

A pesquisa pelas seguintes tags é compatível:

  • Estudos:
    • StudyInstanceUID
    • PatientName
    • PatientID
    • AccessionNumber
    • ReferringPhysicianName
    • StudyDate
  • Séries: todos os termos de pesquisa no nível de estudo
    • SeriesInstanceUID
    • Modalidade
  • Instâncias: todos os termos de pesquisa no nível de estudo/série
    • SOPInstanceUID

Somente o valor único, a correspondência exata é compatível, exceto para StudyDate, que aceita consultas de intervalo, e PatientName, que aceita correspondência difusa.

Os seguintes parâmetros de URL adicionais são compatíveis:

  • fuzzymatching: se definido como true, a correspondência difusa será aplicada à tag PatientName. A correspondência difusa realizará a tokenização e a normalização do valor de PatientName na consulta e o valor armazenado. Ele corresponderá se qualquer token de pesquisa for um prefixo de qualquer token armazenado. Por exemplo, se o PatientName for "John^Doe", então "jo", "Do" e "John Doe" serão todos correspondentes. No entanto, "ohn" não será correspondente.
  • includefield: pode ser definido como uma lista separada por vírgulas de attributeIDs, como IDs de tag de DICOM ou palavras-chave, ou definido como o valor all para retornar todas as tags disponíveis. Para uma lista de tags disponíveis, consulte Resultados retornados.

A paginação é compatível com os parâmetros de consulta limit e offset. Não há um cabeçalho de resposta de aviso se não houver mais resultados disponíveis. Você precisa executar uma consulta extra para determinar se há mais resultados.

  • limit: número máximo de resultados que devem ser retornados, até um limite de 5.000 para estudos/séries e 50.000 para instâncias. O número padrão de resultados é 100 para estudos/séries e 1.000 para instâncias.

  • offset: número de resultados a serem ignorados no início com um limite de 1.000.000.

A diferença de fuso horário do UTC não é compatível.

Resultados retornados

A resposta pode estar no formato JSON ou XML, que pode ser controlado usando os seguintes valores do cabeçalho Accept:

  • application/dicom+json (padrão)
  • multipart/related; type=application/dicom+xml

Por padrão, os seguintes atributos serão retornados:

  • Estudos:
    • SpecificCharacterSet
    • StudyDate
    • StudyTime
    • AccessionNumber
    • InstanceAvailability
    • ReferringPhysicianName
    • TimezoneOffsetFromUTC
    • PatientName
    • PatientID
    • PatientBirthDate
    • PatientSex
    • StudyInstanceUID
    • StudyID
  • Série:
    • SpecificCharacterSet
    • Modalidade
    • TimezoneOffsetFromUTC
    • SeriesDescription
    • SeriesInstanceUID
    • PerformedProcedureStepStartDate
    • PerformedProcedureStepStartTime
    • RequestAttributesSequence
  • Instâncias:
    • SpecificCharacterSet
    • SOPClassUID
    • SOPInstanceUID
    • InstanceAvailability
    • TimezoneOffsetFromUTC
    • InstanceNumber
    • Linhas
    • Colunas
    • BitsAllocated
    • NumberOfFrames

Para includefield=all, os atributos padrão serão retornados junto com os seguintes atributos:

  • Estudos:
    • PersonIdentificationCodeSequence
    • PersonAddress
    • PersonTelephoneNumbers
    • PersonTelecomInformation
    • InstitutionName
    • InstitutionAddress
    • InstitutionCodeSequence
    • ReferringPhysicianIdentificationSequence
    • ConsultingPhysicianName
    • ConsultingPhysicianIdentificationSequence
    • IssuerOfAccessionNumberSequence
    • LocalNamespaceEntityID
    • UniversalEntityID
    • UniversalEntityIDType
    • StudyDescription
    • PhysiciansOfRecord
    • PhysiciansOfRecordIdentificationSequence
    • NameOfPhysiciansReadingStudy
    • PhysiciansReadingStudyIdentificationSequence
    • RequestingServiceCodeSequence
    • ReferencedStudySequence
    • ProcedureCodeSequence
    • ReasonForPerformedProcedureCodeSequence
  • Série:
    • SeriesNumber
    • Laterality
    • SeriesDate
    • SeriesTime
  • Instâncias: todos os atributos presentes na instância DICOM, exceto as seguintes exceções.

Por padrão, searchForInstances não retorna nenhum atributo que tenha um erro Representação de valor de OB, OW ou UN. Para retornar BulkDataURIs para tags correspondentes a prévia Definição de Bulkdata; use o método Prévia searchForInstances.

As tags de sequência DICOM que contêm mais de aproximadamente 1 MiB de dados não serão retornadas na resposta de metadados.

Metadados inconsistentes ou inválidos

No caso de SearchForStudies e SearchForSeries, há um potencial para metadados inconsistentes no nível de estudo e série em várias instâncias. Por exemplo, duas instâncias podem ser enviadas com o mesmo StudyInstanceUID, mas têm StudyDates diferentes. Nesse caso, o comportamento de pesquisa não está bem definido. A pesquisa por esse valor pode funcionar em alguns casos, mas não em outros, e o valor retornado pode variar em diferentes chamadas.

Códigos de status

País Significado
200 (OK) O payload da resposta contém representações para todos os recursos de destino.
400 (Solicitação inválida) A solicitação era inválida (por exemplo, parâmetros de consulta inválidos).
401 (Não autorizado) Faltam credenciais de autenticação na solicitação.
403 (Permissão recusada) O usuário autenticado não tem acesso a esse recurso (ou o recurso não existe).
406 (Não aceitável) O servidor não suporta nenhum dos tipos de mídia aceitáveis.
429 (Há muitas solicitações) O cliente está excedendo a cota.
503 (Serviço não disponível) O servidor não está disponível no momento ou a solicitação excedeu o prazo.

Exclusão

A API Cloud Healthcare é compatível com os seguintes tipos de ação reservada:

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

Eles usam os mesmos caminhos de solicitação que os equivalentes do WADO-RS (RetrieveStudy, RetrieveSeries e RetrieveInstance, respectivamente). Em vez de uma solicitação HTTP GET, uma solicitação DELETE é usada. O efeito é que o estudo, a série ou a instância especificados são excluídos junto com todos os recursos DICOM contidos nele.

Os métodos DeleteStudy e DeleteSeries retornam uma operação de longa duração que exclui todas as instâncias no estudo ou na série. Não é possível inserir instâncias em um estudo ou série que esteja sendo excluída por uma operação até que ela seja concluída.

Consulte Como gerenciar operações de longa duração para um guia de instruções sobre operações.

Uma solicitação DeleteInstance bem-sucedida retorna uma resposta vazia.

Códigos de status

País Significado
200 (OK) O recurso de solicitação foi excluído.
400 (Solicitação inválida) Solicitação inválida.
401 (Não autorizado) Faltam credenciais de autenticação na solicitação.
403 (Permissão recusada) O usuário autenticado não tem acesso a esse recurso (ou o recurso não existe).
429 (Há muitas solicitações) O cliente está excedendo a cota.
503 (Serviço não disponível) O servidor não está disponível no momento ou a solicitação excedeu o prazo.

Cabeçalhos Accept

Alguns dos métodos acima fornecem a capacidade de controlar o formato de resposta usando cabeçalhos Accept HTTP. A correspondência de caracteres curinga é compatível com o nível superior (por exemplo, */*) e subtipo (por exemplo, image/*). Também é possível especificar um valor q para indicar a preferência relativa. Se um valor q não for especificado para um cabeçalho Accept, ele será definido como o valor padrão de 1.0.

Se vários cabeçalhos Accept forem especificados e houver um empate entre os de maior preferência, o servidor escolherá qual usar. Os clientes não devem depender da escolha do cabeçalho Accept do servidor nesse cenário.

Classes SOP compatíveis

A API Cloud Healthcare pode ingerir e fazer a recuperação básica de todas as classes DICOM SOP. Para qualquer recuperação que exija transcodificação entre formatos de imagem, consulte sintaxes de transferência compatíveis com transcodificação para acessar uma lista de as sintaxes de transferência compatíveis.

Versão do dicionário DICOM

A API Cloud Healthcare usa o dicionário DICOM 2022d para analisar tags de instâncias ingeridas.

Para exportar para o BigQuery, a API Cloud Healthcare usa o dicionário DICOM 2024c para gerar nomes de colunas.

Definição da tag Bulkdata (pré-lançamento)

Ao recuperar metadados com métodos de visualização, a API Cloud Healthcare excluirá determinadas tags definidas como dados em massa. Em vez disso, essas tags serão retornadas com metadados com um BulkDataURI que permite que o usuário recupere o conteúdo dessas tags (consulte RetrieveBulkdata). Confira a definição usada pela API Cloud Healthcare:

  • Qualquer tag de dados do Pixel: (7FE0,0008), (7FE0,0009) (7FE0,0010).
  • Qualquer tag com uma RV de OB, OW ou UN.
  • Uma tag com RV de OD, OF ou OL maior que 2 KiB.
    • Por motivos legadas, as tags de instâncias já ingeridas na API Cloud Healthcare podem ser consideradas dados em massa se a tag for maior que 256 B (OF e OL) ou 512 B (OD).
  • Uma tag com um VR de AT, FD, FL, UL ou US e uma multiplicidade de valor (VM) maior que 512.
    • Por motivos legados, as tags de instâncias já ingeridas no A API Cloud Healthcare pode ser considerada em lote se a VM for maior que 64.

Além disso, as seguintes tags são consideradas dados em massa, mas não têm BulkDataURIs quando retornados de métodos de metadados, e o conteúdo não pode ser recuperados usando RetrieveBulkdata:

  • Uma tag com um VR de SQ e um tamanho maior que aproximadamente 1 MiB.