https.onCall için protokol spesifikasyonu

Cloud Functions için https.onCall tetikleyicisi, istek ve yanıt için belirli bir biçime sahip olan bir HTTPS tetikleyicisidir. Bu bölümde, istemci SDK'ları tarafından API'yi uygulamak için kullanılan HTTPS istek ve yanıt biçimleri için bir spesifikasyon sağlanmaktadır. Android, Apple platformları veya web SDK'ları kullanılarak gereksinimleriniz karşılanamıyorsa bu bilgiler işinize yarayabilir.

İstek biçimi: headers

Çağırılabilir tetikleyici uç noktasına gönderilen HTTP isteği, aşağıdaki başlıkları içeren bir POST olmalıdır:

  • Zorunlu: Content-Type: application/json
    • İsteğe bağlı ; charset=utf-8 değerine 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 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ındaki 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 çözerek appId öğesini işleyicinin context alanına ekler. Jeton doğrulanamazsa istek reddedilir. (SDK 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 CORS OPTIONS ön uçuş işlemini tetikler:

  • application/json politikasına izin verilmiyor. text/plain veya application/x-www-form-urlencoded olmalıdır.
  • Authorization başlığı, CORS güvenli listelenmiş istek başlığı değildir.
  • Diğer üstbilgilerin kullanılmasına da izin verilmez.

Ç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 birine sahip bir JSON nesnesi olmalıdır:

  • Zorunlu: data: İşleve iletilen bağımsız değişken. Bu, geçerli bir JSON değeri olabilir. Bu, aşağıda açıklanan serileştirme biçimine göre otomatik olarak yerel JavaScript türlerine dönüştürü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ı oluşmasına neden olabilecek birkaç durum vardır.

  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 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ırsa ancak işlenmemiş bir istisnayla başarısız olursa veya başarısız bir promise döndürürse istek 500 Internal Server Error ile INTERNAL hata koduyla reddedilir. 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ır ve çağrılabilir işlevler için sağlanan API'yi kullanarak 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 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: üstbilgiler

Yanıtın üstbilgileri şunlardır:

  • 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. Yanıt 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 olarak değerlendirmelidir.

  • error: Bu alan varsa HTTP durum kodundan veya data'un da 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 bir JSON nesnesi olmalıdır. Bu nesne, status, message ve (isteğe bağlı olarak) details alanları içerir. 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'sı, kullanıcı tarafından döndürülen değeri bu JSON biçiminde otomatik olarak kodlar. Müşteri SDK'ları, bu parametrelerin kodunu aşağıda açıklanan serileştirme biçimine göre otomatik olarak yerel türlere dönüştürür.

Diğer alanlar varsa yoksayılmalıdır.

Serileştirme

İsteğe bağlı veri yükü 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şleme kullanılarak JSON'da bir proto3 protokol arabelleğindeki Any alanının değeriymiş gibi 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ürler için değere ait tescilli 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:

  • null - null
  • int (32 bite kadar, imzalı veya imzasız) - ör. 3 veya -30.
  • kayan nokta - ör. 3.14
  • çift: ör. 3.14
  • boole: true veya false
  • dize - ör. "hello world"
  • map<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 değerinin JSON'de normalde 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'
}

unsigned long

{
    '@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. İletilen 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 gibi durumlarda, JSONArray iletilmesi List değerini döndürür.

Bilinmeyen @type alanı olan bir harita seri durumdan çıkarılırsa harita olarak bırakılır. Bu sayede geliştiriciler, eski istemcileri bozmadan döndürülen değerlerine yeni türlerde alanlar 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ı bir 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 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 ü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"
        }
    }
}