https.onCall için protokol belirtimi

Bulut İşlevleri için bir https.onCall tetikleyicisi, istek ve yanıt için belirli bir biçime sahip bir HTTPS tetikleyicisidir. 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, Apple platformları veya web SDK'ları kullanılarak karşılanamıyorsa bu bilgiler sizin için yararlı olabilir.

İstek formatı: başlıklar

Çağrılabilir bir tetikleyici uç noktasına yönelik HTTP isteği, aşağıdaki başlıklara sahip bir POST olmalıdır:

  • Gerekli: Content-Type: application/json
    • İsteğe bağlı ; charset=utf-8 izin verilir.
  • İsteğe bağlı: Authorization: Bearer <token>
    • İstekte bulunan oturum açmış kullanıcı için bir Firebase Kimlik Doğrulama kullanıcı kimliği belirteci. Arka uç, bu belirteci otomatik olarak doğrular ve işleyicinin context kullanılabilir hale getirir. Belirteç geçerli değilse, istek reddedilir.
  • İsteğe bağlı: Firebase-Instance-ID-Token: <iid>
    • Firebase istemci SDK'sından FCM kayıt belirteci. Bu bir dize olmalı. Bu, işleyicinin context kullanılabilir. Push bildirimlerini hedeflemek için kullanılır.
  • İsteğe bağlı: X-Firebase-AppCheck: <token>
    • İstekte bulunan istemci uygulaması tarafından sağlanan Firebase Uygulama Kontrolü belirteci. Arka uç, bu belirteci otomatik olarak doğrular ve işleyicinin context appId enjekte ederek kodunu çözer. 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: JavaScript istemcilerinde, bu istekler bir CORS OPTIONS ön kontrolünü tetikler, çünkü:

Çağrılabilir tetikleyici, bu OPTIONS isteklerini otomatik olarak işler.

İstek gövdesi

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

  • Gerekli: data - İşleve iletilen bağımsız değişken. 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ı

Yanıttaki hatalar için farklı HTTP durum kodları ve dize durum kodları ile sonuçlanabilecek birkaç durum vardır.

  1. client tetikleyicisi çağrılmadan önce bir HTTP hatası olması durumunda, yanıt bir istemci işlevi olarak ele alınmaz. Örneğin, bir istemci var olmayan bir işlevi çağırmaya çalışırsa, 404 Not Found yanıtı alır.

  2. İstemci tetikleyicisi çağrılır, ancak istek JSON olmaması, geçersiz alanların olması veya data alanının eksik olması gibi yanlış biçimdeyse, istek INVALID_ARGUMENT hata koduyla 400 Bad Request ile reddedilir.

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

  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 tetikleyici çağrılır, ancak işlenmeyen bir istisna ile başarısız olur veya başarısız bir söz verirse, istek INTERNAL hata koduyla 500 Internal Server Error ile reddedilir. 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. Döndürülen HTTP durum kodu, code.proto içinde tanımlandığı gibi, hata durumunun HTTP durumuyla resmi eşleştirilmesine dayanır. 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. Bu, işlev OK durumuyla açık bir hata döndürürse yanıtın 200 OK durumuna sahip olduğu, ancak yanıtta error alanının ayarlandığı anlamına gelir.

  7. İstemci tetiklemesi başarılıysa yanıt durumu 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 izin verilir.

Yanıt gövdesi

İstemci uç noktasından gelen yanıt her zaman bir JSON nesnesidir. En azından, herhangi bir isteğe bağlı alanla birlikte ya result ya da error içerir. Yanıt bir JSON nesnesi değilse veya data veya error içermiyorsa, istemci SDK'sı isteği, INTERNAL (13) Google hata koduyla başarısız olarak değerlendirmelidir.

  • error - Bu alan mevcutsa, HTTP durum koduna veya data de mevcut olup olmadığına bakılmaksızın isteğin başarısız olduğu kabul edilir. Bu alanın değeri, status , message ve (isteğe bağlı olarak) details için alanlar içeren, hatalar için standart Google Cloud HTTP Eşleme biçiminde bir JSON nesnesi olmalıdır. code alanı dahil edilmeyecektir. status alanı ayarlanmamışsa veya geçersiz bir değerse, istemci, code.proto uyarınca durumu INTERNAL olarak ele almalıdır. details varsa, varsa, istemci SDK'sındaki hataya eklenen herhangi bir kullanıcı bilgisine dahil edilir.
    Not: Buradaki details alanı, kullanıcı tarafından sağlanan bir değerdir. Google Status biçiminde olduğu gibi, proto türüyle anahtarlanmış bir değerler listesi olması gerekmez.
  • result - İşlev tarafından döndürülen değer. 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 yerel türlere otomatik olarak çözer.

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

seri hale getirme

Rastgele veri yükleri için serileştirme formatı, hem istek hem de yanıt için aynıdır.

Platform tutarlılığı için bunlar, standart JSON eşlemesi kullanılarak bir proto3 protokol arabelleğindeki Any alanının değeriymiş gibi JSON'da kodlanır. null , int , double veya string gibi basit türlerin değerleri doğrudan kodlanır ve açık türlerini içermez. Bu nedenle, bir float ve bir double aynı şekilde kodlanır ve aramanın diğer ucunda hangisinin alındığını bilemeyebilirsiniz. JSON'a özgü olmayan türler için, değer için yazılan proto3 kodlaması kullanılır. Daha fazla bilgi için Any JSON kodlamasına ilişkin belgelere bakın.

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

  • boş - null
  • int (imzalı veya imzasız, 32 bite kadar) - örneğin 3 veya -30 .
  • kayan nokta - örneğin 3.14
  • çift ​​- örneğin 3.14
  • boole - 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]

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

long öğesinin normalde JSON'da izin verilmeyen özel bir tür olduğunu, ancak proto3 belirtiminde kapsandığını unutmayın. Ö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'
}

Genel olarak, @type anahtarı ayrılmış olarak kabul edilmeli ve geçirilen haritalar için kullanılmamalıdır.

Basit tipler için tip belirtilmediği için bazı değerler tel üzerinden geçtikten sonra tip değiştirecektir. Geçilen bir float double olur. short , int olur ve bu böyle devam eder. Android'de, liste değerleri için hem List hem de JSONArray desteklenir. Bu durumlarda, bir JSONArray iletmek bir List verir.

@type alanı bilinmeyen bir haritanın serisi kaldırılırsa, 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"
        }
    }
}