Catch up on highlights from Firebase at Google I/O 2023. Learn more

Specyfikacja protokołu dla https.onCall

Wyzwalacz https.onCall dla Cloud Functions to wyzwalacz HTTPS z określonym formatem żądania i odpowiedzi. Ta sekcja zawiera specyfikację formatów żądań i odpowiedzi HTTPS używanych przez zestawy SDK klienta do implementacji interfejsu API. Te informacje mogą być przydatne, jeśli nie można spełnić Twoich wymagań przy użyciu platform Android, Apple lub internetowych zestawów SDK.

Format żądania: nagłówki

Żądanie HTTP do wywoływanego punktu końcowego wyzwalacza musi być POST z następującymi nagłówkami:

  • Wymagane: Content-Type: application/json
    • opcjonalny ; charset=utf-8 jest dozwolone.
  • Opcjonalnie: Authorization: Bearer <token>
    • Token identyfikatora użytkownika uwierzytelniania Firebase dla zalogowanego użytkownika wysyłającego żądanie. Backend automatycznie weryfikuje ten token i udostępnia go w context obsługi. Jeśli token jest nieprawidłowy, żądanie jest odrzucane.
  • Opcjonalnie: Firebase-Instance-ID-Token: <iid>
    • Token rejestracji FCM z pakietu SDK klienta Firebase. To musi być ciąg znaków. Jest to dostępne w context obsługi. Służy do targetowania powiadomień push.
  • Opcjonalnie: X-Firebase-AppCheck: <token>
    • Token sprawdzania aplikacji Firebase dostarczony przez aplikację kliencką wysyłającą żądanie. Backend automatycznie weryfikuje ten token i dekoduje go, wprowadzając appId do context procedury obsługi. Jeśli token nie może zostać zweryfikowany, żądanie jest odrzucane. (Dostępne dla SDK >=3.14.0)

Jeśli zostaną uwzględnione inne nagłówki, żądanie zostanie odrzucone, zgodnie z opisem w dokumentacji odpowiedzi poniżej.

Uwaga: w klientach JavaScript te żądania wyzwalają wstępną inspekcję CORS OPTIONS , ponieważ:

Wyzwalacz wywoływalny automatycznie obsługuje te żądania OPTIONS .

Prośba o treść

Treść żądania HTTP powinna być obiektem JSON z dowolnym z następujących pól:

  • Wymagane: data — Argument przekazany do funkcji. Może to być dowolna poprawna wartość JSON. Jest to automatycznie dekodowane do natywnych typów JavaScript zgodnie z formatem serializacji opisanym poniżej.

Jeśli w żądaniu znajdują się jakiekolwiek inne pola, backend uzna żądanie za źle sformułowane i zostanie odrzucone.

Format odpowiedzi: kody statusu

Istnieje kilka przypadków, które mogą skutkować różnymi kodami stanu HTTP i kodami stanu ciągów dla błędów w odpowiedzi.

  1. W przypadku błędu HTTP przed wywołaniem wyzwalacza client odpowiedź nie jest obsługiwana jako funkcja klienta. Na przykład, jeśli klient próbuje wywołać nieistniejącą funkcję, otrzymuje odpowiedź 404 Not Found .

  2. Jeśli wyzwalacz klienta jest wywoływany, ale żądanie ma niewłaściwy format, na przykład nie jest to JSON, ma nieprawidłowe pola lub brakuje pola data , żądanie jest odrzucane z błędem 400 Bad Request i kodem błędu INVALID_ARGUMENT .

  3. Jeśli token uwierzytelniania podany w żądaniu jest nieprawidłowy, żądanie jest odrzucane z kodem błędu 401 Unauthorized i kodem błędu UNAUTHENTICATED .

  4. Jeśli token rejestracji FCM podany w żądaniu jest nieprawidłowy, zachowanie jest niezdefiniowane. Token nie jest sprawdzany przy każdym żądaniu, z wyjątkiem sytuacji, gdy jest używany do wysłania powiadomienia push z FCM.

  5. Jeśli wyzwalacz wywoływalny zostanie wywołany, ale zakończy się niepowodzeniem z powodu nieobsłużonego wyjątku lub zwróci nieudaną obietnicę, żądanie zostanie odrzucone z komunikatem 500 Internal Server Error i kodem błędu INTERNAL . Zapobiega to przypadkowemu ujawnieniu błędów kodowania użytkownikom końcowym.

  6. Jeśli funkcja wywoływalna zostanie wywołana i zwróci jawny warunek błędu przy użyciu interfejsu API udostępnionego dla funkcji wywoływalnych, żądanie zakończy się niepowodzeniem. Zwrócony kod stanu HTTP jest oparty na oficjalnym mapowaniu stanu błędu na stan HTTP, zgodnie z definicją w code.proto . Konkretny kod błędu, komunikat i zwrócone szczegóły są zakodowane w treści odpowiedzi, jak opisano poniżej. Oznacza to, że jeśli funkcja zwróci jawny błąd ze statusem OK , to odpowiedź ma status 200 OK , ale w odpowiedzi ustawione jest pole error .

  7. Jeśli wyzwalacz klienta zakończy się pomyślnie, stan odpowiedzi to 200 OK .

Format odpowiedzi: nagłówki

Odpowiedź ma następujące nagłówki:

  • Content-Type: application/json
  • opcjonalny ; charset=utf-8 jest dozwolone.

Ciało odpowiedzi

Odpowiedź z punktu końcowego klienta jest zawsze obiektem JSON. Zawiera co najmniej result lub error wraz z polami opcjonalnymi. Jeśli odpowiedź nie jest obiektem JSON, nie zawiera data ani error , pakiet SDK klienta powinien potraktować żądanie jako niepowodzenie z kodem błędu Google INTERNAL (13) .

  • error — Jeśli to pole jest obecne, żądanie jest uznawane za nieudane, niezależnie od kodu stanu HTTP lub obecności data . Wartość tego pola powinna być obiektem JSON w standardowym formacie mapowania HTTP Google Cloud dla błędów, z polami na status , message i (opcjonalnie) details . Pole code nie jest uwzględniane. Jeśli pole status jest nieustawione lub ma niepoprawną wartość, klient powinien traktować status jako INTERNAL , zgodnie z code.proto . Jeśli dostępne są details , są one zawarte we wszelkich informacjach o użytkowniku dołączonych do błędu w pakiecie SDK klienta, jeśli ma to zastosowanie.
    Uwaga: Pole details jest tutaj wartością dostarczoną przez użytkownika. Niekoniecznie jest to lista wartości wpisanych według typu proto, jak w formacie Google Status .
  • result — wartość zwrócona przez funkcję. Może to być dowolna poprawna wartość JSON. Zestaw SDK funkcji firebase automatycznie koduje wartość zwróconą przez użytkownika w tym formacie JSON. Zestawy SDK klienta automatycznie dekodują te parametry do typów natywnych zgodnie z formatem serializacji opisanym poniżej.

Jeśli obecne są inne pola, należy je zignorować.

Serializacja

Format serializacji dla dowolnych ładunków danych jest taki sam zarówno dla żądania, jak i odpowiedzi.

Aby zapewnić spójność platformy, są one kodowane w formacie JSON tak, jakby były wartością pola Any w buforze protokołu proto3, przy użyciu standardowego mapowania JSON . Wartości prostych typów, takich jak null , int , double lub string są kodowane bezpośrednio i nie zawierają jawnego typu. Tak więc float i double są kodowane w ten sam sposób i możesz nie wiedzieć, co jest odbierane po drugiej stronie połączenia. W przypadku typów, które nie są natywne dla formatu JSON, używane jest wpisane kodowanie proto3 dla wartości. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją dotyczącą kodowania Any JSON .

Dozwolone są następujące typy:

  • zero - null
  • int (ze znakiem lub bez znaku, do 32 bitów) - np. 3 lub -30 .
  • pływak - np. 3.14
  • podwójna - np. 3.14
  • wartość logiczna — true lub false
  • string - np. "hello world"
  • mapa - np. {"x": 3}
  • lista - np. [1, 2, 3]
  • long (ze znakiem lub bez znaku, do 64 bitów) - [szczegóły poniżej]

Wartości NaN i Infinity dla wartości float i double nie są obsługiwane.

Zauważ, że long jest typem specjalnym, który zwykle nie jest dozwolony w JSON, ale jest objęty specyfikacją proto3. Na przykład są one zakodowane jako:

długi

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

długi bez znaku

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

Ogólnie rzecz biorąc, klucz @type należy uważać za zarezerwowany i nie należy go używać do przekazywanych map.

Ponieważ typ nie jest określony dla typów prostych, niektóre wartości zmienią typ po przejściu przez przewód. Przekazany float staje się double . short staje się int i tak dalej. W systemie Android dla wartości listy obsługiwane są zarówno List , jak i JSONArray . W takich przypadkach przekazanie JSONArray da List .

Jeśli mapa z nieznanym polem @type jest deserializowana, pozostaje mapą. Dzięki temu programiści mogą dodawać pola z nowymi typami do zwracanych wartości bez psucia starszych klientów.

Próbki kodu

Przykłady w tej sekcji ilustrują sposób kodowania następujących elementów:

  • Przykład callable.call w Swift
  • Pomyślna odpowiedź na wywołanie
  • Odpowiedź na niepowodzenie dla wywołania

Przykład Callable.call w Swift do kodowania

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

Nagłówek żądania:

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

Treść żądania:

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

Odpowiedź na kodowanie

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

Pomyślny nagłówek odpowiedzi:

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

Treść pomyślnej odpowiedzi:

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

Błąd odpowiedzi na kodowanie

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

Nieudany nagłówek odpowiedzi:

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

Treść odpowiedzi zakończonej niepowodzeniem:

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