Specyfikacja protokołu dla https.onCall

https.onCall wyzwalania dla funkcji Chmura jest wyzwalacz HTTPS w formacie specyficznym dla żą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 na żądanie w końcowym wyzwalania 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 ID użytkownika Firebase Authentication dla zalogowanego użytkownika zgłaszającego żądanie. Backend automatycznie weryfikuje ten żeton i udostępnia je w przewodnika context . Jeśli token jest nieważny, żądanie jest odrzucane.
  • Opcjonalnie: Firebase-Instance-ID-Token: <iid>
    • Token rejestracji FCM z pakietu SDK klienta Firebase. To musi być ciąg. Jest ona dostępna w przewodnika context . Służy do kierowania powiadomień push.
  • Opcjonalnie: X-Firebase-AppCheck: <token>
    • Token Firebase App Check dostarczony przez aplikację kliencką wysyłającą żądanie. Backend automatycznie weryfikuje ten żeton i dekoduje go, wstrzykując appId w przewodnika context . Jeśli token nie może zostać zweryfikowany, żądanie jest odrzucane. (Dostępne dla SDK >=3.14.0)

W przypadku dołączenia jakichkolwiek innych nagłówków żądanie jest odrzucane, jak opisano w dokumentacji odpowiedzi poniżej.

Uwaga: Klienci w JavaScript, wnioski te wywołują Cors OPTIONS Inspekcja wstępna, ponieważ:

  • application/json jest niedozwolone. Musi być text/plain lub application/x-www-form-urlencoded .
  • Authorization nagłówka nie jest CORS-safelisted request-header .
  • Inne nagłówki są podobnie niedozwolone.

Wywoływalnym spust automatycznie obsługuje te OPTIONS żądań.

Poproś o treść

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

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

Jeśli w żądaniu występują jakiekolwiek inne pola, zaplecze uznaje żądanie za zniekształcone i zostaje odrzucone.

Format odpowiedzi: kody statusu

Istnieje wiele przypadków, które mogłyby prowadzić do różnych kodów stanu HTTP i kodów stanu ciąg do błędów w odpowiedzi.

  1. W przypadku wystąpienia błędu HTTP, zanim client spust jest wywołany, odpowiedź nie jest traktowane jako funkcja klienta. Na przykład, jeśli klient próbuje powołać się na nieistniejącą funkcję, otrzyma 404 Not Found odpowiedzi.

  2. Jeśli spust klient jest wywoływany, ale wniosek jest w złym formacie, jak nie jest JSON, mający nieprawidłowe pola, lub brakujące data pole, wniosek zostaje odrzucony z 400 Bad Request , z kodem błędu INVALID_ARGUMENT .

  3. Jeśli auth żeton w żądaniu jest nieprawidłowy, wniosek zostaje odrzucony z 401 Unauthorized , z 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 wysyłania powiadomień wypychanych za pomocą FCM.

  5. Jeżeli wymagalne spust jest wywoływany, ale nie z nieobsługiwany wyjątek lub zwróci uszkodzonej obietnicę, wniosek zostaje odrzucony z 500 Internal Server Error , z kodem błędu INTERNAL . Zapobiega to przypadkowemu ujawnieniu błędów kodowania użytkownikom końcowym.

  6. Jeśli wywoływalna funkcja zostanie wywołana i zwróci jawny warunek błędu przy użyciu interfejsu API udostępnionego dla funkcji wywoływalnych, żądanie nie powiedzie się. Kod stanu HTTP zwrócony jest na podstawie oficjalnego odwzorowania stanu błędu do stanu HTTP, jak określono w code.proto . Określony 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 zwraca wyraźny błąd ze statusem OK , a następnie reakcja ma status 200 OK , ale error pole jest ustawione w odpowiedzi.

  7. Jeśli spust klient jest udany, status odpowiedź jest 200 OK .

Format odpowiedzi: nagłówki

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

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

Organ odpowiedzi

Odpowiedź z punktu końcowego klienta jest zawsze obiektem JSON. Przynajmniej zawiera zarówno result lub error , wraz z opcjonalnymi polami. Jeśli odpowiedź nie jest obiekt JSON, lub nie zawiera data lub error , SDK klient powinien traktować jako żądanie nie powiodło się z kodem błędu Google INTERNAL (13) .

  • error - Jeśli to pole jest obecne, a następnie wniosek uznaje się za nie powiodła się, bez względu na kod statusu HTTP czy data jest również obecny. Wartość tej dziedzinie powinny być obiekt JSON w standardowej Google Cloud HTTP mapowania formatu błędów, z polami dla status , message , i (opcjonalnie) details . code pola nie powinny być uwzględnione. Jeżeli status pole jest wyłączony lub jest nieprawidłowa wartość, klient powinien traktować status INTERNAL , zgodnie z code.proto . Jeśli details jest obecny, jest zawarte w każdej informacji użytkownika dołączonym do błędu w SDK klienta, jeśli ma to zastosowanie.
    Uwaga: details pole tutaj jest wartością przez użytkownika. To niekoniecznie jest lista wartości kluczach od rodzaju proto jak w Google Status formacie.
  • result - wartość zwracana przez funkcję. Może to być dowolna prawidłowa wartość JSON. Pakiet SDK funkcji Firebase automatycznie koduje wartość zwróconą przez użytkownika w tym formacie JSON. Zestawy 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 dla żądania, jak i odpowiedzi.

Dla spójności platformy te są kodowane w JSON jakby to wartość w Any dziedzinie, w buforze protokołu proto3 stosując standardowe odwzorowywanie JSON . Wartości typów prostych, takich jak null , int , double lub string kodowane są bezpośrednio i nie obejmują ich wyraźny typ. Tak, float i double są kodowane w ten sam sposób, a może nie wiedzieć, który jest odbierany na drugim końcu połączenia. W przypadku typów, które nie są natywne dla JSON, używane jest wpisane kodowanie proto3 dla wartości. Aby uzyskać więcej informacji, zobacz dokumentację dla dowolnego kodowania JSON .

Dozwolone są następujące typy:

  • null - null
  • int (znakiem lub bez, do 32 bitów), - przykład 3 lub -30 .
  • Pływak - np 3.14
  • Podwójnie - np 3.14
  • Boolean - true czy false
  • Ciąg - np "hello world"
  • mapa - np {"x": 3}
  • lista - na przykład [1, 2, 3]
  • długi (ze znakiem lub bez, do 64 bitów) - [szczegóły poniżej]

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

Należy zauważyć, że long to specjalny rodzaj zazwyczaj zabroniona w JSON, ale objęte opisie proto3. Na przykład są one zakodowane jako:

długie

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

długi bez znaku

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

W ogóle, @type klucz należy uznać zarezerwowane i nie wykorzystywane do przekazywanych w mapach.

Ponieważ typ nie jest określony dla typów prostych, niektóre wartości zmienią typ po przejściu przez przewód. float przekazany staje się double . short staje się int , i tak dalej. W Androidzie, zarówno List i JSONArray są obsługiwane dla wartości listy. W tych przypadkach, przechodzącą w JSONArray przyniesie List .

Jeśli mapa z nieznanym @type pola rozszeregować, to pozostaje jako mapa. Umożliwia to programistom dodawanie pól z nowymi typami do wartości zwracanych bez przerywania 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
  • Udana odpowiedź na wezwanie
  • Odpowiedź niepowodzenia dla połączenia

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ść wniosku:

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

Udana treść odpowiedzi:

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

Niepowodzenie reakcji na kodowanie

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

Nagłówek nieudanej odpowiedzi:

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

Nieudana treść odpowiedzi:

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