https.onCall için protokol spesifikasyonu

Cloud Functions için https.onCall tetikleyicisi, istek ve yanıt için belirli bir biçime sahip bir HTTPS tetikleyicisidir. Bu bölümde, istemci SDK'larının API'yi uygulamak için kullandığı HTTPS istek ve yanıt biçimleri için bir spesifikasyon sağlanmaktadır. Koşullarınızı karşılıyorsanız bu bilgiler sizin için faydalı olabilir. karşılanmaması Android, Apple platformları veya web SDK'ları kullanılarak karşılanamaz.

İstek biçimi: başlıklar

Çağrılanabilir bir tetikleyici uç noktasına yönelik HTTP isteği,POST şu başlıkları ekleyin:

  • Zorunlu: Content-Type: application/json
    • İsteğe bağlı ; charset=utf-8 öğesine izin verilir.
  • İsteğe bağlı: Authorization: Bearer <token>
    • İstekte bulunan giriş yapmış kullanıcının Firebase Authentication kullanıcı kimliği jetonu. Arka uç, bu jetonu otomatik olarak doğrular ve işleyicinin context öğesinde kullanılabilir hale getirir. Jeton 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 jetonu. Bu bir dize olmalıdır. Bu bilgi, işleyicinin context bölümünde yer alır. Push bildirimlerini hedeflemek için kullanılır.
  • İsteğe bağlı: X-Firebase-AppCheck: <token>
    • İsteği yapan istemci uygulaması tarafından sağlanan Firebase Uygulama Kontrolü jetonu. Arka uç, bu jetonu otomatik olarak doğrular ve kodunu çözer. appId, işleyicinin context öğesine ekleniyor. Jeton kullanılamaz doğrulandığında istek reddedilir. (3.14.0 ve sonraki sürümlerde kullanılabilir)

Başka herhangi bir üstbilgi eklenirse, istek, aşağıdaki yanıt dokümanlarında açıklandığı gibi reddedilir.

Not: JavaScript istemcilerinde bu istekler, aşağıdaki nedenlerle bir CORS OPTIONS ön kontrolünü tetikler:

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

İstek içeriği

HTTP isteğinin gövdesi, aşağıdaki alanlardan herhangi birini içeren bir JSON nesnesi olmalıdır:

  • Zorunlu: data: İşleve iletilen bağımsız değişken. Bu, geçerli herhangi bir JSON değeri olabilir. Bu kod, aşağıda açıklanan serileştirme biçimine göre otomatik olarak yerel JavaScript türlerine çözülür.

İstekte başka alanlar varsa arka uç, isteği hatalı biçimli olarak değerlendirir ve reddeder.

Yanıt biçimi: durum kodları

Yanıtta hatalar için farklı HTTP durum kodları ve dize durum kodları ile sonuçlanabilecek çeşitli durumlar vardır.

  1. client tetikleyicisi çağrılmadan önce bir HTTP hatası oluşursa yanıt, 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 (ör. JSON değilse, geçersiz alanlara sahipse veya data alanı eksikse) istek 400 Bad Request ile INVALID_ARGUMENT hata koduyla reddedilir.

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

  4. İstekte sağlanan FCM kayıt jetonu geçersizse davranış tanımlanmaz. Jeton, FCM ile push bildirimi göndermek için kullanıldığı durumlar haricinde her istekte kontrol edilmez.

  5. Çağrılabilir tetikleyici çağrılır ancak işlenmemiş bir istisnayla başarısız olursa veya başarısız bir taahhüt döndürürse istek INTERNAL hata kodu ile 500 Internal Server Error ile reddedilir. Bu sayede kodlama hatalarının son kullanıcılara yanlışlıkla gösterilmesi önlenir.

  6. Çağrılabilir çağrılabilir ve çağrılabilir işlevler için sağlanan API'yi kullanarak 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 eşlemesini temel alır. Döndürülen belirli hata kodu, mesaj ve ayrıntılar, yanıt gövdesinde aşağıda açıklandığı şekilde kodlanı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 tetikleyicisi başarılı olursa yanıt durumu 200 OK olur.

Yanıt biçimi: başlıklar

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

  • Content-Type: application/json
  • İsteğe bağlı ; charset=utf-8 değerine izin verilir.

Yanıt gövdesi

Müşteri uç noktasından gelen yanıt her zaman bir JSON nesnesi olur. En azından isteğe bağlı alanlarla birlikte result veya error içerir. Öğe yanıt JSON nesnesi değil veya data ya da error içermiyorsa istemci SDK'sı isteği başarısız olarak değerlendirmelidir Google hata kodu INTERNAL (13) ile.

  • error: Bu alan mevcutsa HTTP durum kodundan veya data değerinin de mevcut olup olmadığından bağımsız olarak isteğin başarısız olduğu kabul edilir. Bu alanın değeri; status, message ve (isteğe bağlı olarak) details alanlarını içeren hatalar için standart Google Cloud HTTP Eşleme biçiminde bir JSON nesnesi olmalıdır. code alanı dahil edilmez. status alanı ayarlanmamışsa veya geçersiz bir değerse istemci, code.proto'ya uygun olarak durumu INTERNAL olarak ele almalıdır. details mevcutsa istemci SDK'sında hataya eklenmiş kullanıcı bilgilerine (varsa) dahil edilir.
    Not: Buradaki details alanı, kullanıcı tarafından sağlanan bir değerdir. Google Status biçiminde olduğu gibi prototiplere göre anahtarlanmış bir değerler listesi olmayabilir.
  • result: İşlev tarafından döndürülen değer. Bu, geçerli bir JSON değeri olabilir. firebase-functions SDK, kullanıcı tarafından döndürülen değeri otomatik olarak bu JSON biçiminde kodlar. İstemci SDK'ları, aşağıda açıklanan serileştirme biçimine göre bu parametrelerin kodunu otomatik olarak yerel türlere çözer.

Başka alanlar varsa bunlar yoksayılmalıdır.

Serileştirme

Rastgele veri yüklerinin 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 bir Any alanının değeriymiş gibi JSON'de 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, float ve double aynı şekilde kodlanır ve aramanın diğer ucunda hangisinin alındığını bilemezsiniz. JSON'a özgü olmayan türlerde, değer için yazılan proto3 kodlaması kullanılır. Daha fazla bilgi için Herhangi bir JSON kodlamasıyla ilgili dokümanlara bakın.

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

  • boş - null
  • int (imzalı veya imzasız, en fazla 32 bit) - ör. 3 veya -30.
  • kayan - ör. 3.14.
  • çift - ör. 3.14.
  • boole - true veya false
  • dize - ör. "hello world".
  • eşleme<string, any=""> - ör. {"x": 3}</string,>
  • liste (ör. [1, 2, 3])
  • long (imzalı veya imzasız, 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, JSON'da normalde izin verilmeyen ancak proto3 spesifikasyonu kapsamında olan özel bir türdür. Örneğin, bunlar şu şekilde kodlanı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 iletilen haritalar için kullanılmamalıdır.

Basit türler için tür belirtilmediğinden bazı değerler kablodan geçirildikten sonra tür olarak değişir. Geçilen bir float, double haline gelir. short, int haline gelir ve bu şekilde devam eder. Android'de liste değerleri için hem List hem de JSONArray desteklenir. Böyle durumlarda, bir JSONArray'in aktarılması List sonucunu verir.

Bilinmeyen @type alanı olan bir harita seri durumdan çıkarılırsa harita olarak bırakılır. Bu, geliştiricilerin eski müşterileri bozmadan dönüş değerlerine yeni türler içeren alanlar eklemesine olanak tanır.

Kod örnekleri

Bu bölümdeki örneklerde aşağıdakilerin nasıl kodlanacağı gösterilmektedir:

  • Swift'te callable.call örneği
  • Arama için başarılı bir yanıt
  • Arama için hata yanıtı

Kodlamak için Swift'teki 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 içeriği:

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

Kodlama 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 metni:

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

Kodlama yanıtı başarısız

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