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ı 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.

Not: Android, Apple veya web SDK'larını kullanıp kullanamadığınızı kontrol edin. Bu protokolü doğrudan uygulamak yerine bu SDK'ları kullanmanız önerilir. SDK'lar, Uygulamanızdan İşlev Çağırma bölümünde ayrıntılı olarak açıklandığı gibi kodlama süresinden ve eforundan tasarruf etmenizi sağlayacak özellikler sunar.

İ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 alanında 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, işleyicinin context bölümünde bulunur. 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 üstbilgiler eklenirse istek, aşağıdaki yanıt dokümanı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 birini içeren 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, 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. FCM ile push bildirimi göndermek için kullanıldığından hariç olmak üzere, jeton 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 son kullanıcılara yanlışlıkla 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. Müşteri tetikleyicisi başarılıysa yanıt durumu 200 OK olur.

Yanıt biçimi: üstbilgiler

Yanıtta aşağıdaki üstbilgiler bulunur:

• 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 bir JSON nesnesi değilse veya data ya da error içermiyorsa istemci SDK'sı, isteği INTERNAL (13) Google hata koduyla başarısız olarak ele almalıdır.

• 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şlemesi 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ı ile 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, 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'
}

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 kablo üzerinden geçtikten sonra türünü değiştirir. İ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 bir @type alanına sahip bir harita, seri dışına çı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ı yanıtı
• Arama için bir 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 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 ü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"
        }
    }
}