Specyfikacja protokołu dla https.onCall

https.onCall w Cloud Functions to wyzwalacz HTTPS z konkretnym formatem żądania i odpowiedzi. W tej sekcji znajdziesz specyfikację formatów żądań i odpowiedzi HTTPS używanych przez pakiety SDK klienta do implementowania interfejsu API. Te informacje mogą być przydatne, jeśli nie możesz spełnić wymagań za pomocą pakietów SDK dla Androida, Apple lub internetu.

Format żądania: nagłówki

Żądanie HTTP do punktu końcowego wywoływalnego przez regułę musi być POST z tymi nagłówkami:

• Wymagane: Content-Type: application/json
  • Opcjonalny składnik ; charset=utf-8 jest dozwolony.
• Opcjonalnie: Authorization: Bearer <token>
  • Firebase Authentication token identyfikatora użytkownika, który wysyła żądanie. Backend automatycznie weryfikuje ten token i udostępnia go w context modułu obsługi. Jeśli token jest nieprawidłowy, żądanie zostaje odrzucone.
• Opcjonalnie: Firebase-Instance-ID-Token: <iid>
  • Token rejestracji FCM z pakietu SDK klienta Firebase. Musi to być ciąg znaków. Jest ona dostępna w sekcji context. Służy do kierowania powiadomień push.
• Opcjonalnie: X-Firebase-AppCheck: <token>
  • Token Sprawdzania aplikacji Firebase dostarczony przez aplikację klienta przesyłającą żądanie. Backend automatycznie weryfikuje ten token i dekoduje go, wstrzykując appId w elementie context w obsługowniku. Jeśli nie uda się zweryfikować tokena, żądanie zostanie odrzucone. (dostępne w pakiecie SDK w wersji ≥ 3.14.0)

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

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

• application/json – to jest niedozwolone. Musi to być text/plain lub application/x-www-form-urlencoded.
• Nagłówek Authorization nie jest bezpiecznym nagłówkiem żądania CORS.
• Inne nagłówki również nie są dozwolone.

Wyzwalający wywołanie przekażą te żądania OPTIONS do automatycznego przetwarzania.

Treść żądania

Treść żądania HTTP powinna być obiektem JSON z jednym z tych pól:

• Wymagane: data – argument przekazany do funkcji. Może to być dowolna prawidłowa wartość JSON. Jest on automatycznie dekodowany na natywne typy JavaScriptu zgodnie z formatem serializacji opisanym poniżej.

Jeśli w żądaniu znajdują się inne pola, backend uzna je za źle sformułowane i odrzuci je.

Format odpowiedzi: kody stanu

Istnieje kilka przypadków, w których w odpowiedzi mogą występować różne kody stanu HTTP i kod stanu ciągu znaków dla błędów.

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

2. Jeśli wywołany zostanie wyzwalacz klienta, ale żądanie ma nieprawidłowy format (np. nie jest w formacie JSON, zawiera nieprawidłowe pola lub brakuje pola data), żądanie zostanie odrzucone z wartością 400 Bad Request i kodem błędu INVALID_ARGUMENT.

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

4. Jeśli token rejestracji FCM podany w żądaniu jest nieprawidłowy, zachowanie jest nieokreślone. Token nie jest sprawdzany w przypadku każdego żądania, z wyjątkiem sytuacji, gdy jest używany do wysyłania powiadomienia push za pomocą FCM.

5. Jeśli wywołany wyzwalacz funkcji wywoływalnej zwraca błąd z nieobsługiwanym wyjątkiem lub zwraca obietnicę z błędem, żądanie jest odrzucane z wartością 500 Internal Server Error i kodem błędu INTERNAL. Zapobiega to przypadkowemu ujawnieniu błędów w kodzie użytkownikom.

6. Jeśli wywoływana funkcja zostanie wywołana i zwróci jawny stan błędu za pomocą interfejsu API udostępnionego dla funkcji wywoływalnych, żądanie się nie powiedzie. Zwracany kod stanu HTTP jest oparty na oficjalnym mapowaniu stanu błędu na stan HTTP zgodnie z definicją w pliku code.proto. W treści odpowiedzi kod błędu, komunikat i szczegóły są zakodowane w sposób podany poniżej. Oznacza to, że jeśli funkcja zwróci jawny błąd o stanie OK, odpowiedź będzie miała stan 200 OK, ale w odpowiedzi będzie ustawione pole error.

7. Jeśli wywołanie klienta się powiedzie, stan odpowiedzi będzie miał wartość 200 OK.

Format odpowiedzi: nagłówki

Odpowiedź zawiera te nagłówki:

• Content-Type: application/json
• Opcjonalny składnik ; charset=utf-8 jest dozwolony.

Treść odpowiedzi

Odpowiedź z punktu końcowego klienta to zawsze obiekt JSON. Musi ono zawierać co najmniej result lub error oraz dowolne pola opcjonalne. Jeśli odpowiedź nie jest obiektem JSON lub nie zawiera atrybutów data ani error, pakiet SDK klienta powinien potraktować żądanie jako nieudane z kodem błędu Google INTERNAL (13).

• error – jeśli to pole jest obecne, żądanie jest uważane za nieudane niezależnie od kodu stanu HTTP lub obecności pola data. Wartość tego pola powinna być obiektem JSON w standardowym formacie Google Cloud HTTP Mapping dla błędów, z polami status, message i (opcjonalnie) details. Nie należy uwzględniać pola code. Jeśli pole status nie jest skonfigurowane lub zawiera nieprawidłową wartość, klient powinien traktować stan jako INTERNAL zgodnie z plikiem code.proto. Jeśli występuje wartość details, jest ona uwzględniana w informacjach o użytkowniku dołączonych do błędu w pakiecie SDK klienta (w stosownych przypadkach).
  Uwaga: pole details to wartość podana przez użytkownika. Nie musi to być lista wartości posortowana według klucza proto typu, jak w formacie Google Status.
• result – wartość zwrócona przez funkcję. Może to być dowolna prawidłowa wartość JSON. Pakiet SDK firebase-functions automatycznie koduje wartość zwróconą przez użytkownika w formacie JSON. Pakiety SDK klienta automatycznie dekodują te parametry na typy natywne zgodnie z formatem serializacji opisanym poniżej.

Jeśli występują inne pola, należy je zignorować.

Serializacja

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

Aby zachować spójność na platformach, 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, np. null, int, double lub string, są kodowane bezpośrednio i nie zawierają ich typu. Oznacza to, że float i double są kodowane w ten sam sposób i nie wiadomo, który z nich jest odbierany po drugiej stronie połączenia. W przypadku typów, które nie są natywne dla JSON, do wartości używane jest kodowanie proto3. Więcej informacji znajdziesz w dokumentacji dotyczącej kodowania dowolnego formatu JSON.

Dozwolone są te typy:

• null – null
• int (z sygnaturą lub bez, do 32 bitów) – np. 3 lub -30.
• float – np. 3.14
• podwójna – np. 3.14
• Wartość logiczna – true lub false
• ciąg tekstowy – np. "hello world"
• map<string, any=""> – np. {"x": 3}</string,>
• lista – np.[1, 2, 3].
• long (podpisane lub niepodpisane, do 64 bitów) – [szczegóły znajdziesz poniżej]

Wartości NaN i Infinity w przypadku właściwości float i double nie są obsługiwane.

Pamiętaj, że long to typ specjalny, który zwykle nie jest dozwolony w formacie JSON, ale jest objęty specyfikacją proto3. Na przykład są one kodowane jako:

Liczba długa

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

unsigned long

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

Ogólnie klucz @type należy uznać za zarezerwowany i nie używać go do przekazywania map.

Ponieważ typ nie jest określony w przypadku prostych typów, niektóre wartości zmienią typ po przesłaniu przez sieć. Podana wartość float staje się wartością double. short staje się int itd. Na Androidzie w przypadku wartości listy obsługiwane są zarówno List, jak i JSONArray. W takich przypadkach przekazanie tablicy JSONArray spowoduje uzyskanie wartości List.

Jeśli deserializacja mapy z nieznanym polem @type zakończy się powodzeniem, mapa pozostanie w postaci mapy. Umożliwia to deweloperom dodawanie pól z nowymi typami do wartości zwracanych bez zakłócania działania starszych klientów.

Przykładowe fragmenty kodu

Przykłady w tej sekcji pokazują, jak zakodować:

• Przykład callable.call w Swift
• odpowiedź na wywołanie,
• odpowiedź o niepowodzenie wywołania;

Przykład wywołania metody 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ź do zakodowania

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

Nagłówek odpowiedzi pomyślnej:

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

Treść odpowiedzi w przypadku powodzenia:

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

Odpowiedź na błąd podczas kodowania

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

Nagłówek odpowiedzi z błędem:

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

Treść odpowiedzi:

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