Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

Especificação de protocolo para https.onCall

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Um gatilho https.onCall para Cloud Functions é um gatilho HTTPS com um formato específico para a solicitação e a resposta. Esta seção fornece uma especificação para os formatos de solicitação e resposta HTTPS usados ​​pelos SDKs do cliente para implementar a API. Essas informações podem ser úteis se seus requisitos não puderem ser atendidos usando as plataformas Android, Apple ou SDKs da Web.

Formato de solicitação: cabeçalhos

A solicitação HTTP para um endpoint de gatilho que pode ser chamado deve ser um POST com os seguintes cabeçalhos:

  • Requerido: Content-Type: application/json
    • Um opcional ; charset=utf-8 é permitido.
  • Opcional: Authorization: Bearer <token>
    • Um token de ID de usuário do Firebase Authentication para o usuário conectado que faz a solicitação. O back-end verifica automaticamente esse token e o disponibiliza no context do manipulador . Se o token não for válido, a solicitação será rejeitada.
  • Opcional: Firebase-Instance-ID-Token: <iid>
    • O token de registro do FCM do SDK do cliente Firebase. Isso deve ser uma string. Isso está disponível no context do manipulador. Ele é usado para direcionar notificações push.
  • Opcional: X-Firebase-AppCheck: <token>
    • O token do Firebase App Check fornecido pelo aplicativo cliente que faz a solicitação. O backend verifica automaticamente esse token e o decodifica, injetando o appId no context do manipulador. Se o token não puder ser verificado, a solicitação será rejeitada. (Disponível para SDK >=3.14.0)

Se outros cabeçalhos forem incluídos, a solicitação será rejeitada, conforme descrito na documentação de resposta abaixo.

Observação: em clientes JavaScript, essas solicitações acionam uma simulação CORS OPTIONS , porque:

O gatilho que pode ser chamado automaticamente lida com essas solicitações OPTIONS .

Corpo da solicitação

O corpo da solicitação HTTP deve ser um objeto JSON com qualquer um dos seguintes campos:

  • Requerido: data - O argumento passado para a função. Pode ser qualquer valor JSON válido. Isso é decodificado automaticamente em tipos JavaScript nativos de acordo com o formato de serialização descrito abaixo.

Se houver outros campos presentes na solicitação, o back-end considerará a solicitação malformada e será rejeitada.

Formato de resposta: códigos de status

Existem vários casos que podem resultar em diferentes códigos de status HTTP e códigos de status de string para erros na resposta.

  1. No caso de um erro HTTP antes que o gatilho do client seja invocado, a resposta não é tratada como uma função do cliente. Por exemplo, se um cliente tentar invocar uma função inexistente, ele receberá uma resposta 404 Not Found .

  2. Se o gatilho do cliente for invocado, mas a solicitação estiver no formato errado, como não ser JSON, ter campos inválidos ou faltar o campo de data , a solicitação será rejeitada com 400 Bad Request , com um código de erro de INVALID_ARGUMENT .

  3. Se o token de autenticação fornecido na solicitação for inválido, a solicitação será rejeitada com 401 Unauthorized , com um código de erro UNAUTHENTICATED .

  4. Se o token de registro do FCM fornecido na solicitação for inválido, o comportamento será indefinido. O token não é verificado em todas as solicitações, exceto quando é usado para enviar uma notificação por push com o FCM.

  5. Se o gatilho chamável for invocado, mas falhar com uma exceção não tratada ou retornar uma promessa com falha, a solicitação será rejeitada com 500 Internal Server Error , com um código de erro INTERNAL . Isso evita que erros de codificação sejam acidentalmente expostos aos usuários finais.

  6. Se o callable for invocado e retornar uma condição de erro explícita usando a API fornecida para funções callable, a solicitação falhará. O código de status HTTP retornado é baseado no mapeamento oficial do status do erro para o status HTTP, conforme definido em code.proto . O código de erro específico, a mensagem e os detalhes retornados são codificados no corpo da resposta conforme detalhado abaixo. Isso significa que, se a função retornar um erro explícito com status OK , a resposta terá status 200 OK , mas o campo de error será definido na resposta.

  7. Se o acionador do cliente for bem-sucedido, o status da resposta será 200 OK .

Formato de resposta: cabeçalhos

A resposta tem os seguintes cabeçalhos:

  • Content-Type: application/json
  • Um opcional ; charset=utf-8 é permitido.

Corpo de resposta

A resposta de um endpoint do cliente é sempre um objeto JSON. No mínimo, ele contém result ou error , juntamente com quaisquer campos opcionais. Se a resposta não for um objeto JSON ou não contiver data ou error , o SDK do cliente deverá tratar a solicitação como falha com o código de erro do Google INTERNAL (13) .

  • error - Se este campo estiver presente, a solicitação será considerada com falha, independentemente do código de status HTTP ou se data também estiverem presentes. O valor desse campo deve ser um objeto JSON no formato padrão de Mapeamento HTTP do Google Cloud para erros, com campos para status , message e (opcionalmente) details . O campo de code não deve ser incluído. Caso o campo de status não esteja definido, ou seja um valor inválido, o cliente deve tratar o status como INTERNAL , conforme code.proto . Se houver details , eles serão incluídos em todas as informações do usuário anexadas ao erro no SDK do cliente, se aplicável.
    Nota: O campo de details aqui é um valor fornecido pelo usuário. Não é necessariamente uma lista de valores codificados por tipo de protótipo como no formato Google Status .
  • result - O valor retornado pela função. Pode ser qualquer valor JSON válido. O SDK de funções do firebase codifica automaticamente o valor retornado pelo usuário nesse formato JSON. Os SDKs do cliente decodificam automaticamente esses parâmetros em tipos nativos de acordo com o formato de serialização descrito abaixo.

Se outros campos estiverem presentes, eles devem ser ignorados.

Serialização

O formato de serialização para cargas de dados arbitrárias é o mesmo para a solicitação e a resposta.

Para consistência de plataforma, eles são codificados em JSON como se fossem o valor de um campo Any em um buffer de protocolo proto3, usando o mapeamento JSON padrão . Valores de tipos simples como null , int , double ou string são codificados diretamente e não incluem seu tipo explícito. Portanto, um float e um double são codificados da mesma maneira e você pode não saber qual é recebido na outra extremidade da chamada. Para tipos que não são nativos de JSON, a codificação proto3 tipada para o valor é usada. Para obter mais informações, consulte a documentação de Qualquer codificação JSON .

Os seguintes tipos são permitidos:

  • nulo - null
  • int (assinado ou não assinado, até 32 bits) - por exemplo, 3 ou -30 .
  • flutuar - por exemplo, 3.14
  • duplo - por exemplo, 3.14
  • boolean - true ou false
  • string - por exemplo, "hello world"
  • mapa - por exemplo, {"x": 3}
  • Lista - por exemplo [1, 2, 3]
  • long (assinado ou não assinado, até 64 bits) - [veja abaixo para detalhes]

Os valores NaN e Infinity para float e double não são suportados.

Observe que long é um tipo especial que normalmente não é permitido em JSON, mas é coberto pela especificação proto3. Por exemplo, eles são codificados como:

grandes

{
    '@type': 'type.googleapis.com/google.protobuf.Int64Value',
    'value': '-123456789123456'
}

longo não assinado

{
    '@type': 'type.googleapis.com/google.protobuf.UInt64Value',
    'value': '123456789123456'
}

Em geral, a chave @type deve ser considerada reservada e não usada para mapas passados.

Como o tipo não é especificado para tipos simples, alguns valores mudarão de tipo depois de passar pela conexão. Um float passado torna-se um double . Um short se torna um int e assim por diante. No Android, tanto List quanto JSONArray são compatíveis com valores de lista. Nesses casos, passar um JSONArray produzirá um List .

Se um mapa com um campo @type desconhecido for desserializado, ele será deixado como um mapa. Isso permite que os desenvolvedores adicionem campos com novos tipos aos seus valores de retorno sem quebrar os clientes mais antigos.

Amostras de código

Os exemplos nesta seção ilustram como codificar o seguinte:

  • Um exemplo callable.call em Swift
  • Uma resposta de sucesso para a chamada
  • Uma resposta de falha para a chamada

Exemplo de Callable.call em Swift para codificar

callable.call([
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23,
    "aLong": -123456789123456 as Int64
])

Cabeçalho da solicitação:

Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token

Corpo da solicitação:

{
    "data": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23,
        "aLong": {
            "@type": "type.googleapis.com/google.protobuf.Int64Value",
            "value": "-123456789123456"
        }
    }
}

Resposta para codificar

return {
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23
};

Cabeçalho de resposta bem-sucedido:

200 OK
Content-Type: application/json; charset=utf-8

Corpo de resposta bem-sucedido:

{
    "response": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23
    }
}

Resposta de falha para codificar

throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
  "some-key": "some-value"
});

Cabeçalho de resposta com falha:

401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8

Corpo de resposta com falha:

{
    "error": {
        "message": "Request had invalid credentials.",
        "status": "UNAUTHENTICATED",
        "details": {
            "some-key": "some-value"
        }
    }
}