Specyfikacja protokołu dla https.onCall

Aktywator https.onCall dla Cloud Functions to aktywator HTTPS z tagiem określonego formatu żą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 Twoje wymagania których nie można zrealizować za pomocą platform Androida i Apple ani internetowych pakietów SDK.

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
  • Dozwolona jest opcjonalna wartość ; charset=utf-8.
• 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 jest odrzucane.
• Opcjonalnie: Firebase-Instance-ID-Token: <iid>
  • Token rejestracji FCM z pakietu SDK klienta Firebase. Musi to być ciąg znaków. Te dane są dostępne w context modułu obsługi. Służy do kierowania na powiadomienia push.
• Opcjonalnie: X-Firebase-AppCheck: <token>
  • Token Sprawdzania aplikacji Firebase udostępniony przez aplikację kliencką, która tworzy użytkownika. Backend automatycznie weryfikuje token i dekoduje go, wstrzykiwanie elementu appId w elemencie context modułu obsługi. Jeśli token nie może być zostanie odrzucona. (Dostępne w przypadku SDK w wersji 3.14.0 lub nowszej).

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

Uwaga: w klientach JavaScriptu te żądania aktywują proces wstępny 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.

Aktywator z możliwością wywołania automatycznie obsługuje te OPTIONS żądania.

Treść żądania

Treść żądania HTTP powinna być obiektem JSON z dowolnym 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 JavaScript zgodnie z opisanym poniżej formatem serializacji.

Jeśli w żądaniu występują inne pola, backend uznaje żądanie za uszkodzone i odrzuca 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 aktywatora client odpowiedź nie jest obsługiwana jako funkcja klienta. Jeśli na przykład klient próbuje wywołać nieistniejącą funkcję, otrzymuje 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 jest odrzucane z wartością 400 Bad Request i kodem błędu INVALID_ARGUMENT.

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

4. Jeśli token rejestracji FCM podany w żądaniu jest nieprawidłowy, działanie jest niezdefiniowane. Token nie jest sprawdzany w każdym żądaniu z wyjątkiem sytuacji, gdy jest on używany do wysyłania powiadomień push w FCM.

5. Jeśli wywoływany aktywator jest wywoływany, ale kończy się niepowodzeniem z powodu nieobsłużonego wyjątku lub zwrócono nieudaną obietnicę, żądanie zostanie odrzucone z kodem 500 Internal Server Error z 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 jawne warunki błędu za pomocą interfejsu API udostępnionego dla funkcji wywoływalnych, żądanie się nie powiedzie. Zwracany kod stanu HTTP opiera się na oficjalnym zmapowaniu stanu błędu na stan HTTP, zgodnie z definicją w code.proto. Konkretny kod błędu, komunikat i zwracane szczegóły są zakodowane w treści odpowiedzi w sposób opisany poniżej. Oznacza to, że jeśli funkcja zwraca jawny błąd o stanie OK, odpowiedź ma stan 200 OK, ale w odpowiedzi jest ustawione pole error.

7. Jeśli aktywator klienta się uruchomi, stan odpowiedzi to 200 OK.

Format odpowiedzi: nagłówki

Odpowiedź ma te nagłówki:

• Content-Type: application/json
• Dozwolona jest opcjonalna wartość ; charset=utf-8.

Treść odpowiedzi

Odpowiedź z punktu końcowego klienta to zawsze obiekt JSON. Musi ona 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 uznawane za nieudane niezależnie od kodu stanu HTTP i tego, czy występuje też data. W przypadku błędów wartość tego pola powinna być obiektem JSON w standardowym formacie mapowania HTTP Google Cloud, z polami status, message i (opcjonalnie) details. Pole code nie powinno zostać uwzględnione. Jeśli pole status nie jest ustawione 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ść zwracaną przez użytkownika w tym formacie JSON. Pakiety SDK klienta automatycznie dekodują te parametry na typy natywne zgodnie z opisanym poniżej formatem serializacji.

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

Serializacja

Format serializacji dowolnych ładunków danych jest taki sam zarówno dla żą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, takich jak null, int, double i string, są kodowane bezpośrednio i nie uwzględniają ich jednoznacznego 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 formatu JSON, używane jest kodowanie proto3 typu proto3. Więcej informacji znajdziesz w dokumentacji kodowania JSON.

Dozwolone są te typy:

• null – null
• int (podpisana lub niepodpisana, do 32-bitowa) – np. 3 lub -30.
• float – np. 3.14
• podwójny – np. 3.14
• logiczna – true lub false
• ciąg znaków, np. "hello world"
• map<string, any=""> – np. {"x": 3}</string,>
• lista – np. [1, 2, 3]
• długi (podpisany lub niepodpisany, 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 specjalny typ niedozwolony w formacie JSON, ale podlega specyfikacji proto3. Na przykład są one zakodowane w taki sposób:

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 map przekazywanych jako argumenty.

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

Jeśli mapa z nieznanym polem @type została poddana deserializacji, pozostanie ona mapą. Dzięki temu deweloperzy mogą dodawać do wartości zwracanych pola z nowymi typami pola bez zakłócania pracy 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ź na niepowodzenie połączenia,

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ź na kodowanie

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

Nagłówek odpowiedzi, która powiodła się:

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 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"
        }
    }
}