Declaração de conformidade com a norma DICOM

Os arquivos DICOM na Cloud Healthcare API suportam um subconjunto dos serviços Web RESTful especificados na norma DICOM PS3.18 – Serviços Web (normalmente referida como DICOMweb). Especificamente, suportam os recursos e o serviço Studies (anteriormente denominados serviços WADO-RS, STOW-RS e QIDO-RS).

Além disso, a Cloud Healthcare API suporta um serviço Web proprietário para eliminar instâncias DICOM.

A Cloud Healthcare API não suporta o URI Service, o Worklist Service, o Non-Patient Instance Service nem nenhuma das Capabilities Transactions.

Obtenha a transação

O Retrieve Transaction é um serviço Web RESTful para obter dados de imagens DICOM.

A API Retrieve Transaction suporta a obtenção dos seguintes recursos:

  • Recursos DICOM:
    • Estudo
    • Série
    • Instância
    • Molduras
    • Bulkdata
  • Recursos de metadados
    • Estudo
    • Série
    • Instância
  • Recursos renderizados
    • Instância
    • Molduras

Não suporta recursos de miniaturas.

Consulte Quotas e limites para ver detalhes sobre quotas e limites para estes métodos.

Estudo/série/instâncias DICOM

Os seguintes cabeçalhos Accept são suportados:

  • multipart/related; type="application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 (predefiniçã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 suporta tipos de conteúdo de parte única para maior comodidade:

  • 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=*

Isto não faz parte da norma DICOMweb oficial.

Frames DICOM

Os seguintes cabeçalhos Accept são suportados:

  • multipart/related; type="application/octet-stream"; transfer-syntax=1.2.840.10008.1.2.1 (predefiniçã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 ao utilizador pedir que não seja feita nenhuma transcodificação, pelo que será usada a sintaxe de transferência do ficheiro carregado. Para application/octet-stream, os dados em massa são devolvidos no formato em que aparecem no ficheiro DICOM carregado.

Recursos renderizados

Os seguintes cabeçalhos Accept são suportados:

  • image/jpeg (predefinição)
  • image/png

Apenas é suportada a obtenção de recursos de instância ou frame.

Não são suportados parâmetros de URL além de Viewport.

Recursos de metadados

Os seguintes cabeçalhos Accept são suportados:

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

As etiquetas codificadas como elementos InlineBinary são codificadas através da ordenação de bytes little-endian, uma vez que o parâmetro de sintaxe de transferência não é suportado em pontos finais que pedem recursos de metadados.

RetrieveMetadata vai incluir BulkDataURIs para etiquetas que correspondam à definição de dados em massa.

As etiquetas de sequência DICOM que contenham mais de aproximadamente 1 MiB de dados não são devolvidas em recursos de metadados. Esta limitação aplica-se apenas aos recursos de metadados. Os recursos DICOM continuam a conter estas etiquetas.

Recursos de dados em massa

Os seguintes cabeçalhos Accept são suportados:

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

Sintaxes de transferência suportadas para transcodificação

Os cabeçalhos Accept acima descrevem os tipos de suportes e as sintaxes de transferência que pode pedir à API, mas isto nem sempre é possível, consoante a sintaxe de transferência do ficheiro original que foi carregado. Em particular, a transcodificação só é possível a partir das seguintes sintaxes de transferência:

  • 1.2.840.10008.1.2 (Little Endian implícito)
  • 1.2.840.10008.1.2.1 (Little Endian explícito)
  • 1.2.840.10008.1.2.2 (VR explícito Big Endian)
  • 1.2.840.10008.1.2.4.50 (JPEG Baseline Process 1)
  • 1.2.840.10008.1.2.4.57 (JPEG sem perdas)
  • 1.2.840.10008.1.2.4.70 (JPEG Lossless Selection Value 1)
  • 1.2.840.10008.1.2.4.90 (apenas sem perdas JPEG 2000)
  • 1.2.840.10008.1.2.4.91 (JPEG 2000)
  • 1.2.840.10008.1.2.5 (RLE sem perdas)

Se o ficheiro original tiver uma sintaxe de transferência diferente da que consta na lista acima e pedir a transcodificação para outro formato, é devolvido um erro.

A Cloud Healthcare API não consegue transcodificar imagens não monocromáticas com uma profundidade de bits superior a 8 para JPEG. Além disso, as imagens com um valor de Bits Allocated (0028, 0100) de 1 ou que estão armazenadas em etiquetas Float Pixel Data (7FE0,0008) ou Double Float Pixel Data (7FE0,0009) só podem ser transcodificadas entre formatos nativos.

Para desativar a transcodificação e obter qualquer ficheiro da API, pode definir transfer-syntax=* no cabeçalho Accept.

Códigos de estado

Código Significado
200 (OK) A carga útil da resposta contém representações de todos os recursos de destino.
400 (Pedido errado) O pedido era inválido (por exemplo, parâmetros de consulta ou cabeçalhos incorretos) para os recursos de destino especificados (por exemplo, dados de píxeis em falta).
401 (Não autorizado) O pedido não tem credenciais de autenticação.
403 (Autorização recusada) O utilizador autenticado não tem acesso a este recurso (ou o recurso não existe).
406 (Não aceitável) O servidor não suporta nenhum dos tipos de suportes aceitáveis.
429 (Demasiados pedidos) O cliente está a exceder a respetiva quota.
503 (Serviço indisponível) O servidor está atualmente indisponível ou o pedido excedeu o respetivo prazo.

Transação na loja

A transação de loja é um serviço Web RESTful para armazenar dados de imagens DICOM.

A transação da loja aceita diretamente ficheiros binários DICOM da Parte 10 ou aceita a divisão de um ficheiro DICOM em metadados (representados em JSON) e dados em massa. Estas 2 versões têm semânticas diferentes que são descritas nas secções seguintes.

Consulte Quotas e limites para ver detalhes sobre quotas e limites para este método.

Ficheiros binários DICOM parte 10

Os seguintes tipos de conteúdo são suportados:

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

O servidor não força nem substitui atributos.

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

Tenha em atenção que, por conveniência, a transação da loja também aceita um pedido HTTP de uma única parte com uma única instância DICOM com o tipo de conteúdo application/dicom. Isto não faz parte da norma DICOMweb oficial.

Consulte o artigo Armazene uma instância DICOM para aceder ao guia de instruções associado.

Metadados JSON e pedidos de dados em massa

Quando armazena instâncias através de metadados JSON e dados em massa, a primeira parte multipart tem de consistir numa matriz JSON de instâncias DICOM.

A primeira parte tem de ter um Content-Type de application/dicom+json; transfer-syntax=TransferSyntaxUID onde TransferSyntaxUID é a sintaxe de transferência que foi usada para codificar dados binários em objetos InlineBinary. Se não estiverem presentes objetos InlineBinary nos metadados, o parâmetro transfer-syntax pode ser omitido.

Os seguintes elementos DICOM têm de estar presentes em todas as instâncias nos metadados JSON:

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

O elemento SpecificCharacterSet tem de estar definido como ISO_IR 192, e os metadados JSON têm de estar codificados em Unicode UTF-8. O TransferSyntaxUID pode ser definido para qualquer sintaxe de transferência válida, exceto para as seguintes sintaxes de transferência não suportadas:

  • 1.2.840.10008.1.2.2 (VR explícito Big Endian)
  • 1.2.840.10008.1.2.1.99 (Deflated Explicit VR Little Endian)

Nos metadados JSON, o utilizador pode especificar vários BulkDataURIs para etiquetas DICOM com VRs de OB, OW ou UN. Estes BulkDataURIs indicam que os dados binários da etiqueta que contém o URI vão ser enviados numa parte seguinte com o cabeçalho Content-Location definido como o BulkDataURI.

Cada instância nos metadados JSON pode ter, no máximo, um BulkDataURI. Não podem existir BulkDataURIs duplicados nos metadados JSON. Os dados em massa de imagens comprimidas só podem ser enviados para a etiqueta PixelData e, quando enviados, a sintaxe de transferência especificada na parte de dados em massa tem de corresponder ao valor do elemento TransferSyntaxUID da instância.

Os seguintes tipos de conteúdo são suportados para 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/dicom-rle; transfer-syntax=1.2.840.10008.1.2.5
  • image/jls; transfer-syntax=1.2.840.10008.1.2.​4.​80
  • image/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. Isto é suportado para todas as etiquetas, exceto PixelData, que tem de ser enviada como parte de dados em massa. Quando são usados objetos InlineBinary nos metadados JSON, a sintaxe de transferência usada para a codificação tem de ser especificada no Content-Type da parte de metadados JSON.

O servidor não deriva atributos de macro de descrição de píxeis de imagem.

Consulte o artigo Crie instâncias DICOM a partir de metadados JSON e ficheiros JPEG para aceder ao guia de instruções associado.

Resposta

Em caso de erro, é devolvida uma etiqueta FailureDetail (0009, 0097) adicional (para respostas XML) ou uma etiqueta FailureDetailJSON (0009,1097) (para respostas JSON). A etiqueta FailureDetail fornece uma descrição legível do erro.

Se uma instância DICOM tiver a mesma tupla que outra instância já existente no arquivo DICOM, é devolvido um erro Processing failure com uma etiqueta FailureDetail "já existe".<StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID>

A resposta pode estar no formato JSON ou XML, que pode ser controlada através dos seguintes valores do cabeçalho Accept:

  • application/dicom+xml (predefinição)
  • application/dicom+json

Códigos de estado

Código Significado
200 (OK) O recurso foi armazenado com êxito.
400 (Pedido errado) O pedido era inválido (por exemplo, tipo de suporte ou sintaxe de transferência não suportados).
401 (Não autorizado) O pedido não tem credenciais de autenticação.
403 (Autorização recusada) O utilizador autenticado não tem acesso a este recurso (ou o recurso não existe).
406 (Não aceitável) O servidor não suporta nenhum dos tipos de suportes aceitáveis.
409 (Conflito) Pelo menos um recurso não foi armazenado com êxito (por exemplo, um ficheiro DICOM inválido). Verifique a etiqueta FailureDetail no corpo da resposta para mais informações.
429 (Demasiados pedidos) O cliente está a exceder a respetiva quota.
503 (Serviço indisponível) O servidor está atualmente indisponível ou o pedido excedeu o respetivo prazo.

Pesquise transações

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

A API Cloud Healthcare suporta a pesquisa de estudos, séries e instâncias.

Parâmetros de pesquisa

A pesquisa pelas seguintes etiquetas é suportada:

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

Apenas é suportada a correspondência exata de valor único, exceto para StudyDate, que suporta consultas de intervalo, e PatientName, que suporta a correspondência aproximada.

Os seguintes parâmetros de URL adicionais são suportados:

  • fuzzymatching: se estiver definida como true, a correspondência aproximada é aplicada à etiqueta PatientName. A correspondência aproximada realiza a tokenização e a normalização do valor de PatientName na consulta e do valor armazenado. Vai haver correspondência se qualquer token de pesquisa for um prefixo de qualquer token armazenado. Por exemplo, se PatientName for "John^Doe", "jo", "Do" e "John Doe" vão corresponder. No entanto, "ohn" não vai corresponder.
  • includefield: pode ser definido como uma lista de IDs de atributos separados por vírgulas, como IDs de etiquetas DICOM ou palavras-chave, ou definido como o valor all para devolver todas as etiquetas disponíveis. Para ver uma lista das etiquetas disponíveis, consulte a secção Resultados devolvidos.

A paginação é suportada através dos parâmetros de consulta limit e offset. Não existe um cabeçalho de resposta de aviso se não estiverem disponíveis mais resultados. Tem de executar uma consulta adicional para determinar se existem mais resultados.

  • limit: número máximo de resultados que devem ser devolvidos, até um máximo de 5000 para estudos/séries e 50 000 para instâncias. O número predefinido de resultados é 100 para estudos/séries e 1000 para instâncias.

  • offset: número de resultados a ignorar no início até um máximo de 1 000 000.

O desvio do fuso horário em relação à Hora Universal Coordenada (UTC) não é suportado.

Resultados devolvidos

A resposta pode estar no formato JSON ou XML, que pode ser controlada através dos seguintes valores do cabeçalho Accept:

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

Por predefinição, são devolvidos os seguintes atributos:

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

Para includefield=all, os atributos predefinidos são devolvidos juntamente 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
    • Lateralidade
    • SeriesDate
    • SeriesTime
  • Instâncias: todos os atributos presentes na instância DICOM, excluindo as seguintes exceções.

As etiquetas de sequência DICOM que contenham mais de aproximadamente 1 MiB de dados não são devolvidas na resposta de metadados.

Metadados inconsistentes/inválidos

No caso de SearchForStudies/SearchForSeries, existe um potencial de metadados ao nível do estudo/série inconsistentes em várias instâncias. Por exemplo, podem ser carregadas duas instâncias com o mesmo StudyInstanceUID, mas com StudyDates diferentes. Neste caso, o comportamento de pesquisa não está bem definido. A pesquisa por esse valor pode funcionar em alguns casos, mas não noutros, e o valor devolvido pode variar em diferentes chamadas.

Códigos de estado

Código Significado
200 (OK) A carga útil da resposta contém representações de todos os recursos de destino.
400 (Pedido errado) O pedido era inválido (por exemplo, parâmetros de consulta inválidos).
401 (Não autorizado) O pedido não tem credenciais de autenticação.
403 (Autorização recusada) O utilizador autenticado não tem acesso a este recurso (ou o recurso não existe).
406 (Não aceitável) O servidor não suporta nenhum dos tipos de suportes aceitáveis.
429 (Demasiados pedidos) O cliente está a exceder a respetiva quota.
503 (Serviço indisponível) O servidor está atualmente indisponível ou o pedido excedeu o respetivo prazo.

Eliminação

A API Cloud Healthcare suporta os seguintes tipos de ações proprietárias:

  • DeleteStudy
  • DeleteSeries
  • DeleteInstance

Estes usam os mesmos caminhos de pedidos que as respetivas contrapartes WADO-RS (RetrieveStudy, RetrieveSeries e RetrieveInstance, respetivamente). Em vez de um pedido HTTP GET, é usado um pedido DELETE. O efeito é que o estudo, a série ou a instância especificados são eliminados juntamente com todos os recursos DICOM contidos nos mesmos.

Os métodos DeleteStudy e DeleteSeries devolvem uma operação de longa duração que elimina todas as instâncias no estudo ou na série. Tenha em atenção que não é possível inserir instâncias num estudo ou numa série que esteja a ser eliminada por uma operação até que a operação seja concluída.

Consulte o artigo Gerir operações de longa duração para ver um guia de instruções sobre operações.

Um pedido DeleteInstance bem-sucedido devolve uma resposta vazia.

Códigos de estado

Código Significado
200 (OK) O recurso de pedido foi eliminado.
400 (Pedido errado) O pedido era inválido.
401 (Não autorizado) O pedido não tem credenciais de autenticação.
403 (Autorização recusada) O utilizador autenticado não tem acesso a este recurso (ou o recurso não existe).
429 (Demasiados pedidos) O cliente está a exceder a respetiva quota.
503 (Serviço indisponível) O servidor está atualmente indisponível ou o pedido excedeu o respetivo prazo.

Cabeçalhos de aceitação

Alguns dos métodos acima permitem controlar o formato de resposta através de cabeçalhos HTTP Accept. A correspondência com carateres universais é suportada ao nível superior (por exemplo, */*) e no subtipo (por exemplo, image/*). A especificação de um valor q também é suportada para indicar a preferência relativa. Se não for especificado um valor q para um cabeçalho Accept, este é definido como o valor predefinido de 1,0.

No caso de serem especificados vários cabeçalhos Accept e existir um empate entre os cabeçalhos Accept de preferência mais elevada, o servidor escolhe o cabeçalho Accept. Os clientes não devem depender da escolha do cabeçalho Accept do servidor neste cenário.

Classes SOP suportadas

A Cloud Healthcare API pode carregar e fazer a obtenção básica de todas as classes SOP DICOM. Para qualquer obtenção que exija transcodificação entre formatos de imagem, consulte as sintaxes de transferência suportadas para transcodificação para ver uma lista de sintaxes de transferência suportadas.

Versão do dicionário DICOM

A Cloud Healthcare API usa o dicionário DICOM 2025b para analisar as etiquetas de instâncias carregadas e para gerar nomes de colunas quando exporta para o BigQuery.

Definição de dados em massa

Ao obter metadados, a Cloud Healthcare API exclui determinadas etiquetas que estão definidas como dados em massa. Em alternativa, estas etiquetas são devolvidas juntamente com os metadados com um BulkDataURI que permite ao utilizador obter os conteúdos destas etiquetas (consulte RetrieveBulkdata). Segue-se a definição usada pela API Cloud Healthcare:

  • Qualquer etiqueta de dados do Pixel: (7FE0,0008), (7FE0,0009) (7FE0,0010).
  • Qualquer etiqueta com um VR de OB, OW ou UN.
  • Uma etiqueta com um VR de OD, OF, OL ou OV superior a 2 KiB.
    • Por motivos de compatibilidade com versões anteriores, as etiquetas de instâncias já carregadas na API Cloud Healthcare podem ser consideradas dados em massa se a etiqueta for superior a 256 B (OF e OL) ou 512 B (OD).
  • Uma etiqueta com um VR de AT, FD, FL, UL, US, SV ou UV e tem uma multiplicidade de valores (VM) superior a 512.
    • Por motivos de compatibilidade com versões anteriores, as etiquetas de instâncias já carregadas na Cloud Healthcare API podem ser consideradas dados em massa se a VM for superior a 64.

Além disso, as seguintes etiquetas são consideradas bulkdata, mas não têm BulkDataURIs quando são devolvidas de métodos de metadados e não é possível obter conteúdos através de RetrieveBulkdata:

  • Uma etiqueta com um VR de SQ e um tamanho superior a aproximadamente 1 MB.