Catch up on highlights from Firebase at Google I/O 2023. Learn more

https.onCall için protokol belirtimi

Cloud Functions için 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 işinize yarayabilir.

İstek biçimi: başlıklar

Çağrılabilir bir tetik 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
    • Opsiyonel ; 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ğrulaması 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 alınan FCM kayıt belirteci. Bu bir dizi olmalıdır. Bu, işleyicinin context mevcuttur. 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ğrulanamıyorsa 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ına ve dize durum kodlarına neden olabilecek birkaç durum vardır.

  1. client tetikleyicisi çağrılmadan önce bir HTTP hatası olması durumunda, yanıt bir istemci işlevi olarak işlenmez. Ö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ırsa ancak istek yanlış biçimdeyse, örneğin JSON olmaması, geçersiz alanlara sahip olması veya data alanının eksik olması gibi istek, INVALID_ARGUMENT hata koduyla 400 Bad Request ile reddedilir.

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

  4. İstekte sağlanan FCM kayıt belirteci geçersizse, davranış tanımsızdır. Belirteç, FCM ile 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 özel durumla başarısız olursa 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 gösterilmesini önler.

  6. Çağrılabilir çağrılırsa 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'da tanımlandığı gibi, hata durumunun HTTP durumuyla resmi olarak eşlenmesine dayanır. Döndürülen belirli hata kodu, mesaj ve ayrıntılar, aşağıda ayrıntıları verildiği şekilde yanıt gövdesinde kodlanmıştır. Bu, işlev OK durumunda açık bir hata döndürürse, yanıtın 200 OK durumunda olduğu, ancak error alanının yanıtta ayarlandığı anlamına gelir.

  7. İstemci tetikleyici başarılı olursa, yanıt durumu 200 OK olur.

Yanıt formatı: başlıklar

Yanıtta aşağıdaki başlıklar bulunur:

  • Content-Type: application/json
  • Opsiyonel ; charset=utf-8 izin verilir.

Yanıt gövdesi

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

  • error - Bu alan mevcutsa, HTTP durum kodundan veya data de mevcut olup olmadığından bağımsız olarak istek başarısız kabul edilir. Bu alanın değeri, hatalar için standart Google Cloud HTTP Eşleme biçiminde, status , message ve (isteğe bağlı olarak) details alanlarıyla birlikte bir JSON nesnesi olmalıdır. code alanı dahil edilmeyecektir. status alanı ayarlanmamışsa veya geçersiz bir değerse, müşteri durumu code.proto uyarınca INTERNAL olarak ele almalıdır. details varsa, varsa, istemci SDK'sındaki hataya eklenmiş 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, protokol türüne göre anahtarlanan 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 otomatik olarak bu JSON biçimine kodlar. İstemci SDK'ları, aşağıda açıklanan serileştirme biçimine göre bu parametreleri otomatik olarak yerel türlere çözer.

Başka alanlar mevcutsa, yok sayılmalıdırlar.

Serileştirme

İsteğe bağlı veri yükleri için serileştirme biçimi, 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 double aynı şekilde kodlanır ve aramanın diğer ucunda hangisinin alındığını bilemezsiniz. 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 encoding belgelerine bakın.

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

  • boş - null
  • int (işaretli veya işaretsiz, 32 bit'e 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 (işaretli veya işaretsiz, 64 bit'e kadar) - [ayrıntılar için aşağıya bakın]

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

long normalde JSON'da izin verilmeyen özel bir tür olduğunu, ancak proto3 belirtimi kapsamında olduğunu 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 düşünülmeli ve aktarılan haritalar için kullanılmamalıdır.

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

Bilinmeyen bir @type alanına sahip bir harita seri durumdan çıkarılırsa harita olarak kalır. Bu, geliştiricilerin eski istemcileri bozmadan dönüş değerlerine yeni türlere sahip alanlar eklemelerine olanak tanır.

Kod örnekleri

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

  • Swift'de callable.call örneği
  • Arama 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 gövdesi:

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

Kodlama için başarısızlık 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"
        }
    }
}