Verificar atualizações

A API /osc/checkForUpdates identifica atualizações de estado comparando o último stateFingerprint conhecido do cliente ao fingerprint atual da câmera.

Entrada

Nome Tipo Descrição
stateFingerprint String Impressão digital do estado da câmera desde a última vez que o cliente chamou /osc/state ou /osc/checkForUpdates.
waitTimeout Número inteiro (opcional) Número de segundos para aguardar a mudança de estado da câmera antes de retornar a resposta. Quando waitTimeout expirar, a câmera vai retornar uma resposta mesmo que a impressão digital não tenha sido modificada. Se uma mudança de estado for detectada antes que waitTimeout expire ou se waitTimeout for omitido, a câmera vai retornar a resposta imediatamente.Observação:a câmera pode retornar uma resposta antes que waitTimeout tenha expirado, mesmo que a impressão digital não tenha sido alterada, mas a prática recomendada é esperar até que waitTimeout expire.

Observações de implementação da câmera:

  • Ao receber essa chamada, a câmera compara a impressão digital do estado atual com o parâmetro stateFingerprint recebido. Se a impressão digital tiver sido alterada, a câmera deverá retornar a nova impressão digital imediatamente.

Saída

Nome Tipo Descrição
stateFingerprint String Nova impressão digital do estado da câmera, a mesma da API /osc/state.
throttleTimeout Número inteiro Número recomendado de segundos para o cliente aguardar antes da próxima chamada para checkForUpdates. Os clientes podem fazer solicitações antes que throttleTimeout expire, e as câmeras precisam permitir essas solicitações antecipadas, se possível.

Observações de implementação do cliente:

  • Ao receber uma resposta, o cliente precisa comparar o stateFingerprint recebido com a cópia dele. Se eles não corresponderem, o cliente precisará solicitar o estado atual da câmera usando a API _/osc/state.
  • Os clientes inteligentes limitam as solicitações independentemente da resposta da câmera. Por exemplo, se uma câmera retornar uma resposta não padrão (imediatamente, sem nenhuma mudança e um throttleTimeout) baixo ou 0, o cliente precisará impor seu próprio throttleTimeout antes de solicitar outro checkForUpdates da câmera).

Observações de implementação da câmera:

  • Ao responder a checkForUpdates, a câmera precisa determinar um throttleTimeout razoável. Se a câmera oferecer suporte à lógica de solicitação de longa data (responder somente após waitTimeout se o estado não tiver mudado), não há problema em retornar throttleTimeout como 0. Nesse caso, os clientes podem solicitar atualizações imediatamente.
  • Se a câmera oferecer suporte apenas a respostas rápidas (não recomendado), ela precisará retornar um throttleTimeout razoável para evitar tráfego constante de solicitação/resposta com o cliente. Por exemplo, um throttleTimeout razoável seria de 60 segundos, para permitir uma solicitação do cliente por minuto.
  • A prática recomendada é retornar um throttleTimeout apropriado para os recursos da câmera. Se o servidor não conseguir determinar um throttleTimeout apropriado devido a um problema, a câmera responderá com um código de status 5XX e um corpo JSON contendo o código de erro serverError.

Erro

Código do erro Descrição
missingParameter stateFingerprint não foi especificado.
invalidParameterName Um ou mais nomes de parâmetros de entrada não foram reconhecidos.
invalidParameterValue Os nomes dos parâmetros são reconhecidos, mas um ou mais valores são inválidos. Por exemplo, waitTimeout está fora do intervalo ou o tipo está incorreto.
serverError O servidor não conseguiu determinar um valor throttleTimeout apropriado para a resposta. O problema do servidor será identificado pelo valor 5XX retornado na resposta. Os fabricantes de câmeras precisam fornecer uma tabela de códigos 5XX e os estados de servidor correspondentes que podem gerar esse erro.

Exemplo
Solicitação 
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1

{
    "stateFingerprint": "12EGA33",
    "waitTimeout": 300
}
Resposta 
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff

{
    "stateFingerprint": "12EGA86",
    "throttleTimeout": 60
}
Solicitação 
POST /osc/checkForUpdates HTTP/1.1
Host: [camera ip address]:[httpUpdatesPort]
Content-Type: application/json;charset=utf-8
Accept: application/jsonContent-Length: {CONTENT_LENGTH}
X-XSRF-Protected: 1

{
    "stateFingerprint": "12EGA33",
    "waitTimeout": 300
}
Resposta 
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=utf-8
Content-Length: {CONTENT_LENGTH}
X-Content-Type-Options: nosniff

{
    "name": "camera.checkForUpdates",
    "state": "error",
    "error": {
        "code": "missingParameter",
        "message": "parameter stateFingerprint is missing."
    }
}