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 serão codificadas usando a ordenação de bytes small-endian, parâmetro de sintaxe de transferência não é compatível com endpoints que solicitam recursos de metadados.
Por padrão, RetrieveMetadata não retorna atributos que tenham um erro DICOM
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
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.
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 consultar 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 o mesmo <StudyInstanceUID, SeriesInstanceUID, SOPInstanceUID>
como outra instância que já está no repositório DICOM, um erro de Falha no processamento
for retornado com a mensagem tag FailureDetail.
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 comotrue
, 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 valorall
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 o após 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.
Restrições de valor da tag
O valor da tag BitsAllocated
precisa ser um múltiplo de 8 para o frame
recuperação.
Definição de tag de 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
junto com os metadados com um BulkDataURI que permite ao usuário recuperar conteúdos
dessas tags (consulte
RetrieveBulkdata
).
Confira a seguir a definição usada pela API Cloud Healthcare:
- Qualquer tag com RV de OB, OW ou ONU.
- Uma tag com RV de OD, OF ou OL maior que 2 KiB.
- Por motivos legados, as tags das instâncias já ingeridas no A API Cloud Healthcare poderá ser considerada Bulkdata se a tag for maior que 256 B (OF e OL) ou 512 B (OD).
- Uma tag com RV de AT, FD, FL, UL ou US e tem um valor
Multiplicidade (VM) maior que 512.
- Por motivos legados, as tags das 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
PixelData
.- Uma tag com RV de SQ e tamanho maior que aproximadamente 1 MiB.