https.onCall için protokol spesifikasyonu

Cloud Functions için https.onCall tetikleyici, 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çimleriyle ilgili bir spesifikasyon sağlanmaktadır. Bu bilgiler, Android, Apple platformları veya web SDK'ları kullanılarak gereksinimleriniz karşılanamıyorsa sizin için faydalı olabilir.

İstek biçimi: başlıklar

Çağrılabilir bir tetikleyici uç noktasına yapılan HTTP isteği, aşağıdaki başlıklarla birlikte POST olmalıdır:

  • Zorunlu: Content-Type: application/json
    • İsteğe bağlı ; charset=utf-8 öğesine izin verilir.
  • İsteğe bağlı: Authorization: Bearer <token>
    • İsteği gönderen, oturum açmış kullanıcı için Firebase Authentication kullanıcı kimliği jetonu. Arka uç, bu jetonu otomatik olarak doğrular ve işleyicinin context içinde 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 değer bir dize olmalıdır. Bu özellik, işleyicinin context bölümünde kullanılabilir. 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ğrulayıp kodunu çözer ve işleyicinin context içine appId öğesini yerleştirir. Jeton doğrulanamazsa istek reddedilir. (SDK >=3.14.0 için kullanılabilir)

Başka üstbilgiler eklenirse istek, aşağıdaki yanıt dokümanında açıklandığı gibi reddedilir.

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

Çağrılabilir 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, aşağıda açıklanan serileştirme biçimine göre yerel JavaScript türlerine otomatik olarak çözülür.

İstek içinde başka alanlar varsa arka uç, isteği hatalı biçimlendirilmiş olarak kabul eder ve istek reddedilir.

Yanıt biçimi: durum kodları

Yanıtın hatalarında farklı HTTP durum kodları ve dize durum kodlarına neden olabilecek ç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 mevcut olmayan bir işlevi çağırmaya çalışırsa 404 Not Found yanıtı alır.

  2. İstemci tetikleyici çağrılırsa ancak istek yanlış biçimdeyse (ör. JSON biçiminde olmaması, geçersiz alanlar içermesi veya data alanının eksik olması) istek 400 Bad Request ile INVALID_ARGUMENT hata koduyla reddedilir.

  3. İstekle birlikte gönderilen kimlik doğrulama jetonu geçersizse istek, 401 Unauthorized ile reddedilir ve hata kodu UNAUTHENTICATED olur.

  4. İstekte sağlanan FCM kayıt jetonu geçersizse davranış tanımlanmamıştır. Jeton, FCM ile push 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şlenmemiş bir istisna nedeniyle başarısız olursa veya başarısız bir söz döndürürse istek, 500 Internal Server Error ile reddedilir ve INTERNAL hata kodu döndürülür. Bu sayede kodlama hatalarının yanlışlıkla son kullanıcılara gösterilmesi önlenir.

  6. Çağrılabilir işlev çağrılırsa ve çağrılabilir işlevler için sağlanan API kullanılarak açık bir hata durumu döndürülürse istek başarısız olur. Döndürülen HTTP durum kodu, code.proto dosyasında tanımlandığı gibi hata durumunun HTTP durumuna resmi olarak eşlenmesine dayanır. Döndürülen hata kodu, mesaj ve ayrıntılar, yanıt gövdesinde aşağıda ayrıntılı olarak açıklanan şekilde kodlanır. Bu, işlev OK durumuyla açık bir hata döndürürse yanıtın durumunun 200 OK olacağı ancak yanıtta error alanının ayarlanacağı anlamına gelir.

  7. İstemci tetikleyici 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 sahip:

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

Yanıt gövdesi

Bir istemci 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 hata kodu INTERNAL (13) ile başarısız olmuş olarak değerlendirmelidir.

  • error: Bu alan varsa HTTP durum kodundan veya data alanının da mevcut olup olmaması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 bir JSON nesnesi olmalıdır. Bu nesnede status, message ve (isteğe bağlı olarak) details alanları bulunur. code alanı dahil edilmeyecektir. status alanı ayarlanmamışsa veya geçersiz bir değere sahipse istemci, code.proto'ya uygun olarak durumu INTERNAL olarak değerlendirmelidir. details varsa istemci SDK'sındaki hataya eklenen kullanıcı bilgilerine dahil edilir (geçerli olduğu durumlarda).
    Not: Buradaki details alanı, kullanıcı tarafından sağlanan bir değerdir. Google Status biçiminde olduğu gibi, proto türüne göre anahtarlanmış bir değer listesi olması gerekmez.
  • 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ı, bu parametreleri aşağıda açıklanan serileştirme biçimine göre yerel türlere otomatik olarak çözer.

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

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, 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ğerin türü belirtilmiş proto3 kodlaması kullanılır. Daha fazla bilgi için Any JSON kodlamasıyla ilgili dokümanlara bakın.

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

  • null - null
  • int (işaretli veya işaretsiz, 32 bit'e kadar) - ör. 3 veya -30.
  • float - ör. 3.14
  • çift - ör. 3.14
  • boolean - true veya false
  • dize (ör. "hello world")
  • map<string, any=""> - e.g. {"x": 3}</string,>
  • liste - ör. [1, 2, 3]
  • long (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 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'
}

unsigned long

{
    '@type': 'type.googleapis.com/google.protobuf.UInt64Value',
    'value': '123456789123456'
}

Genel olarak @type anahtarının ayrılmış olarak kabul edilmesi ve iletilen haritalar için kullanılmaması gerekir.

Basit türler için tür belirtilmediğinden, bazı değerler kablo üzerinden geçtikten sonra tür değiştirir. float iletisi double iletisine dönüşür. short, int olur. Android'de liste değerleri için hem List hem de JSONArray desteklenir. Bu gibi durumlarda, JSONArray iletmek List sonucunu verir.

Bilinmeyen bir @type alanı içeren bir harita seri durumdan çıkarılırsa harita olarak kalır. Bu sayede geliştiriciler, eski istemcileri bozmadan yeni türler içeren alanları dönüş değerlerine ekleyebilir.

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ı yanıt
  • Arama için hata yanıtı

Kodlamak için Swift'te 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"
        }
    }
}

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

Kodlanacak hata yanıtı

throw new HttpsError("unauthenticated", "Request had invalid credentials.", {
  "some-key": "some-value"
});

Başarısız yanıt üstbilgisi:

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