https.onCall için protokol spesifikasyonu

Cloud Functions için https.onCall tetikleyicisi, bu biçimi kullanabilirsiniz. Bu bölümde, istemci SDK'ları tarafından kullanılan HTTPS isteği ve yanıt biçimleri için spesifikasyon API'yi uygulamaya dökelim. 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>
    • İstemci uygulaması tarafından sağlanan Firebase Uygulama Kontrolü jetonu isteği gönderin. 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 SDK sürümleri için 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 birine sahip bir JSON nesnesi olmalıdır:

  • Gerekli: data - İşleve aktarılan 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ğin hatalı olduğunu kabul eder ve reddedilir.

Yanıt biçimi: durum kodları

Farklı HTTP durum kodlarına ve hatalar için dize durum kodları kullanıcı olabilir.

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

  2. İstemci tetikleyicisi çağrıldı ancak istek yanlış biçimdeyse (ör. JSON değilse, geçersiz alanlara sahipse veya data alanı eksikse) istek INVALID_ARGUMENT hata kodu ile 400 Bad Request ile reddedilir.

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

  4. İstekte sağlanan FCM kayıt jetonu geçersizse davranış tanımsızdır. 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 koduyla 500 Internal Server Error ile reddedilir. Bu sayede, kodlama hatalarının yanlışlıkla son kullanıcılara 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 bölümünde tanımlandığı gibi, hata durumunun HTTP durumuyla resmi olarak eşleştirilmesine dayanır. Döndürülen belirli hata kodu, mesaj ve ayrıntılar, aşağıda açıklandığı şekilde yanıt gövdesine kodlanır. Bu, işlev OK durumuyla ilgili açık bir hata döndürürse yanıtın 200 OK durumuna sahip olacağı 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 öğesine izin verilir.

Yanıt gövdesi

İstemci uç noktasından gelen yanıt her zaman JSON nesnesidir. En azından result veya error ile birlikte isteğe bağlı alanları 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 edilmemelidir. status alanı ayarlanmazsa veya geçersiz bir değerse istemci, durumu code.proto'ya uygun olarak INTERNAL olarak değerlendirmelidir. details mevcutsa istemci SDK'sındaki hataya eklenen tüm kullanıcı bilgilerine (varsa) eklenir.
    . Not: Buradaki details alanı kullanıcı tarafından sağlanan bir değerdir. Bu her zaman, Google Status biçimindeki proto türüne göre anahtarlanan değerlerin bir listesi değildir.
  • result: İşlev tarafından döndürülen değer. Bu, geçerli herhangi 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ı bilemeyebilirsiniz. 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]
  • uzun (imzalı veya imzasız, en fazla 64 bit) - [ayrıntılar için aşağıya bakın]

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

long etiketinin normalde JSON'de izin verilmeyen özel bir tür olduğunu, ancak proto3 spesifikasyonunun kapsamında olduğunu unutmayın. Ö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 örnekler, aşağıdakilerin nasıl kodlanacağını gösterir:

  • Swift'teki bir 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 gövdesi:

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