Join us for Firebase Summit on November 10, 2021. Tune in to learn how Firebase can help you accelerate app development, release with confidence, and scale with ease. Register

https.onCall için protokol belirtimi

Bir https.onCall Bulut Fonksiyonlar için tetikleyici istek ve yanıt için belirli bir biçimi ile bir HTTPS tetikleyicidir. Bu bölüm, API'yi uygulamak için istemci SDK'ları tarafından kullanılan HTTPS isteği ve yanıt biçimleri için bir belirtim sağlar. Gereksinimleriniz Android, iOS veya web SDK'ları kullanılarak karşılanamıyorsa bu bilgiler sizin için yararlı olabilir.

İstek formatı: başlıklar

Bir çağrılabilir tetik bitiş noktasına HTTP isteği a olmalıdır POST aşağıdaki başlıklarıyla:

  • Gerekli: Content-Type: application/json
    • İsteğe bağlı ; charset=utf-8 bırakılır.
  • İsteğe bağlı: Authorization: Bearer <token>
    • İstekte bulunan oturum açmış kullanıcı için bir Firebase Authentication kullanıcı kimliği belirteci. Arka uç otomatik doğrular belirteç bu ve işleyici içinde kullanılabilir hale getirir context . Belirteç geçerli değilse, istek reddedilir.
  • Opsiyonel: Firebase-Instance-ID-Token: <iid>
    • Firebase istemci SDK'sından FCM kayıt belirteci. Bu bir dize olmalı. Bu işleyici mevcuttur context . Push bildirimlerini hedeflemek için kullanılır.
  • Opsiyonel: X-Firebase-AppCheck: <token>
    • İstekte bulunan istemci uygulaması tarafından sağlanan Firebase Uygulama Kontrolü belirteci. Arka uç otomatik jeton bu doğrular ve enjekte bunu deşifre appId işleyicisi'nın içinde context . Belirteç doğrulanamazsa, istek reddedilir. (SDK >=3.14.0) için kullanılabilir

Başka başlıklar dahil edilirse, aşağıdaki yanıt belgelerinde açıklandığı gibi istek reddedilir.

Not: In JavaScript istemcileri, bu istekleri bir CORS tetikleyebilir OPTIONS çünkü ön kontrol:

  • application/json izin verilmez. Bu olmalıdır text/plain veya application/x-www-form-urlencoded .
  • Authorization başlığı bir değil CORS-safelisted istek başlığı .
  • Diğer başlıklara da benzer şekilde izin verilmez.

Çağrılabilir tetik otomatik olarak bu işler OPTIONS istekleri.

İstek gövdesi

HTTP isteğinin gövdesi, aşağıdaki alanlardan herhangi birine sahip bir JSON nesnesi olmalıdır:

  • : Gerekli data - işleve geçirilen argümanı. Bu, herhangi bir geçerli JSON değeri olabilir. Bu, aşağıda açıklanan serileştirme biçimine göre yerel JavaScript türlerine otomatik olarak çözülür.

İstekte başka alanlar varsa, arka uç, isteği hatalı biçimlendirilmiş olarak kabul eder ve reddedilir.

Yanıt formatı: durum kodları

İçin farklı HTTP durum kodları ve dize durum kodları yol açabilecek çeşitli durumlar vardır hatalar yanıt olarak.

  1. Önce bir HTTP hatası durumunda client tetik çağrılır yanıtı müşteri fonksiyonu olarak ele alınır. Bir istemci varolmayan işlevini çağırmak çalışırsa Örneğin, bir aldığı 404 Not Found yanıtı.

  2. İstemci tetik çağrılan, ancak istek böyle, JSON olmanın geçersiz alanlar olan veya eksik olarak değil, biçimi yanlış ise data alanını, istek ile reddedilir 400 Bad Request bir hata koduyla, INVALID_ARGUMENT .

  3. İstekte sağlanan belirteç kimlik doğrulama geçersizse istek ile reddedilir 401 Unauthorized bir hata koduyla, UNAUTHENTICATED .

  4. İstekte sağlanan FCM kayıt belirteci geçersizse, davranış tanımsızdır. Belirteç, FCM ile bir anında iletme bildirimi göndermek için kullanıldığı durumlar dışında her istekte kontrol edilmez.

  5. Çağrılabilir tetik çağrılan, ancak istisnası ile başarısız veya başarısız bir söz verir ise, istek ile reddedilir 500 Internal Server Error bir hata koduyla, INTERNAL . Bu, kodlama hatalarının yanlışlıkla son kullanıcılara maruz kalmasını önler.

  6. Çağrılabilir çağrılır ve çağrılabilir işlevler için sağlanan API kullanılarak açık bir hata koşulu döndürürse, istek başarısız olur. Tanımlandığı gibi gelen HTTP durum kodu, statü HTTP hata durumunun resmi haritalama dayanmaktadır code.proto . Döndürülen belirli hata kodu, ileti ve ayrıntılar, aşağıda ayrıntılı olarak açıklandığı gibi yanıt gövdesinde kodlanmıştır. Fonksiyon durumu ile açık bir hata verir, bu araçlar o OK , daha sonra yanıt durumu vardır 200 OK , ama error alan cevaben ayarlanır.

  7. İstemci tetik başarılı olursa, tepki durumudur 200 OK .

Yanıt formatı: başlıklar

Yanıt aşağıdaki başlıklara sahiptir:

  • Content-Type: application/json
  • İsteğe bağlı ; charset=utf-8 bırakılır.

Yanıt gövdesi

İstemci uç noktasından gelen yanıt her zaman bir JSON nesnesidir. En azından o da içeren result veya error isteğe bağlı herhangi alanları ile birlikte. Yanıtı bir JSON nesnesi değil veya içermiyorsa data veya error Google hata kodu ile başarısız olarak, istemci SDK isteğini davranmalı INTERNAL (13) .

  • error - bu alan varsa, o zaman isteği başarısız oldu kabul edilir, ne olursa olsun HTTP durum kodu veya ister data de mevcuttur. Bu alanın değeri standart bir JSON nesnesi olmalı , Google Cloud HTTP Haritalama için alanları ile hatalar için biçimi, status , message , ve (isteğe bağlı) details . code alanı dahil edilmeyecektir. Eğer status alan kaldırılırsa ya da geçersiz bir değerdir, istemci olarak statüsünü davranmalı INTERNAL uyarınca, code.proto . Eğer details varsa, bu değer varsa, istemci SDK hata bağlı herhangi bir kullanıcı bilgi dahildir.
    Not: details burada alan bir kullanıcı tarafından sağlanan bir değerdir. Mutlaka Google gibi proto tipi anahtarlı bir değerler listesi değildir Status formatında.
  • result - işlevi tarafından döndürülen değeri. Bu, herhangi bir geçerli JSON değeri olabilir. Firebase-functions SDK, kullanıcı tarafından döndürülen değeri bu JSON formatına otomatik olarak kodlar. İstemci SDK'ları, aşağıda açıklanan serileştirme biçimine göre bu paramların kodunu otomatik olarak yerel türlere çözer.

Başka alanlar varsa, bunlar göz ardı edilmelidir.

seri hale getirme

İsteğe bağlı veri yükleri için serileştirme biçimi, hem istek hem de yanıt için aynıdır.

Bunlar, bir değerini sanki platformu tutarlılığı için bu JSON kodlanır Any bir proto3 protokolü tamponu alanda kullanılarak, standart JSON eşleme . Gibi basit türleri Değerleri null , int , double veya string doğrudan kodlanıyor ve onların açık türünü içermez. Yani, bir float ve double aynı şekilde kodlanıyor ve aramanın diğer ucundaki alındığı bilmiyor olabilir. JSON'a özgü olmayan türler için, değer için yazılan proto3 kodlaması kullanılır. Daha fazla bilgi için, bkz Herhangi JSON kodlama belgelerine .

Aşağıdaki türlere izin verilir:

  • Boş - null
  • int (32 bit kadar, imzalı veya imzasız) - örneğin 3 veya -30 .
  • şamandıra - örneğin 3.14
  • çift - örneğin 3.14
  • boolean - true veya false
  • dize - örneğin "hello world"
  • harita - örneğin, {"x": 3}
  • liste - örneğin, [1, 2, 3]
  • uzun (imzalı veya imzasız, 64 bite kadar) - [ayrıntılar için aşağıya bakın]

NaN ve Infinity değerleri için float ve double desteklenmez.

Not long normal JSON izin özel bir türüdür, ancak proto3 tarifname kapsamındadır. Örneğin, bunlar şu şekilde kodlanmıştır:

uzun

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

imzasız uzun

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

Genelde, @type anahtar olarak kabul ayrılmalıdır ve geçirilen haritalar için kullanılmaz.

Basit tipler için tip belirtilmediği için bazı değerler tel üzerinden geçtikten sonra tip değiştirecektir. Bir float geçirilen bir hale double . Bir short bir hale gelir int ve bu kadar. Android'de, her iki List ve JSONArray liste değerleri için desteklenir. Bu gibi durumlarda, bir JSONArray içinde geçen bir verecektir List .

Bilinmeyen bir bir harita varsa @type alanına serisi kaldırılan edilir, bu bir harita olarak bırakılır. Bu, geliştiricilerin eski istemcileri bozmadan dönüş değerlerine yeni türlere sahip alanlar eklemesine olanak tanır.

Kod örnekleri

Bu bölümdeki örnekler, aşağıdakilerin nasıl kodlanacağını gösterir:

  • Swift'de callable.call örneği
  • Çağrı için bir başarı yanıtı
  • Çağrı için bir başarısızlık yanıtı

Kodlamak için Swift'de Callable.call örneği

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

İstek başlığı:

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

İstek gövdesi:

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

kodlamaya yanıt

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

Başarılı yanıt başlığı:

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

Başarılı yanıt organı:

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

Kodlama hatası yanıtı

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

Başarısız yanıt başlığı:

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

Başarısız yanıt gövdesi:

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