https.onCall için protokol belirtimi

Bulut İşlevleri için https.onCall tetikleyicisi, istek ve yanıt için belirli bir biçime sahip bir HTTPS tetikleyicisidir. Bu bölümde, API'yi uygulamak için istemci SDK'ları tarafından kullanılan HTTPS isteği ve yanıt biçimlerine ilişkin bir belirtim sağlanır. Gereksinimlerinizin Android, Apple platformları veya web SDK'ları kullanılarak karşılanamaması durumunda bu bilgiler sizin için yararlı olabilir.

İstek formatı: başlıklar

Çağrılabilir 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 Firebase Authentication kullanıcı kimliği jetonu. Arka uç bu belirteci otomatik olarak doğrular ve onu 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ındaki FCM kayıt jetonu. Bu bir dize olmalı. Bu, işleyicinin context mevcuttur. Anlık bildirimleri 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ü jetonu. Arka uç bu belirteci otomatik olarak doğrular ve kodunu çözerek appId işleyicinin context enjekte eder. Belirteç doğrulanamıyorsa istek reddedilir. (SDK >=3.14.0 için kullanılabilir)

Başka başlıklar eklenirse istek, aşağıdaki yanıt belgelerinde açıklandığı gibi 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.

Talep gövdesi

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

  • Gerekli: data - İşleve aktarılan argüman. Bu herhangi bir geçerli JSON değeri olabilir. Bunun kodu, aşağıda açıklanan serileştirme formatına göre otomatik olarak yerel JavaScript türlerine dönüştürülür.

İstekte başka alanlar varsa arka uç isteğin hatalı biçimlendirildiğini düşünür 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, 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ırsa ancak istek JSON olmaması, geçersiz alanlara sahip olması veya data alanının eksik olması gibi yanlış biçimdeyse istek 400 Bad Request ve INVALID_ARGUMENT hata koduyla 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 bildirim göndermek için kullanıldığı durumlar dışında her istekte kontrol edilmez.

  5. Çağrılabilir tetikleyici çağrılırsa ancak işlenmeyen bir istisnayla başarısız olursa veya başarısız bir söz döndürürse, istek 500 Internal Server Error ile ve INTERNAL hata koduyla reddedilir. Bu, kodlama hatalarının kazara son kullanıcıların eline geçmesini ö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ülü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şleştirilmesine dayanır. Döndürülen spesifik 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şlevin OK durumuyla açık bir hata döndürmesi durumunda yanıtın 200 OK durumuna sahip olacağı ancak error alanının yanıtta ayarlanacağı anlamına gelir.

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

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, 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ı, isteği Google INTERNAL (13) 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, hatalar için standart Google Cloud HTTP Eşleme biçiminde, status , message ve (isteğe bağlı olarak) details alanlarını içeren bir JSON nesnesi olmalıdır. code alanı dahil edilmeyecektir. status alanı ayarlanmamışsa veya geçersiz bir değerse, istemcinin durumu code.proto uyarınca INTERNAL olarak ele alması gerekir. details mevcutsa, istemci SDK'sındaki hataya eklenen kullanıcı bilgilerine (varsa) eklenir.
    Not: Buradaki details alanı kullanıcı tarafından sağlanan bir değerdir. Bu, Google Status biçiminde olduğu gibi mutlaka protokol türüne göre anahtarlanan değerlerin bir listesi değildir.
  • result - İşlev tarafından döndürülen değer. Bu herhangi bir geçerli JSON değeri olabilir. Firebase işlevleri SDK'sı, 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 formatına göre bu parametrelerin kodunu otomatik olarak yerel türlere dönüştürür.

Başka alanlar mevcutsa bunların göz ardı edilmesi gerekir.

Serileştirme

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 proto3 protokol arabelleğindeki Any bir alanı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. Dolayısıyla, float ve 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 Herhangi bir JSON kodlamasına ilişkin belgelere bakın.

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

  • boş - null
  • int (imzalı veya imzasız, 32 bit'e kadar) - örneğin 3 veya -30 .
  • kayan nokta - ö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 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 spesifikasyonu 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ının ayrılmış olduğu düşünülmeli ve aktarılan haritalar için kullanılmamalıdır.

Basit tipler için tip belirtilmediğinden bazı değerler kabloyu geçtikten sonra tip değiştirecektir. Aktarılan bir float double olur. short , int olur ve bu şekilde devam eder. Android'de liste değerleri için hem List hem de JSONArray desteklenir. Bu durumlarda, bir JSONArray'in iletilmesi List sonucunu verecektir.

Bilinmeyen @type alanına sahip bir haritanın seri durumdan çıkarılması durumunda 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östermektedir:

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

Swift'de kodlamak için 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

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

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