Bulut İşlevleri için bir https.onCall
tetikleyicisi, istek ve yanıt için belirli bir biçime sahip bir HTTPS tetikleyicisidir. Bu bölüm, API'yi uygulamak için istemci SDK'ları tarafından kullanılan HTTPS isteği ve yanıt biçimleri için bir belirtim sağlar. Gereksinimleriniz Android, Apple platformları veya web SDK'ları kullanılarak karşılanamıyorsa bu bilgiler sizin için yararlı olabilir.
İstek formatı: başlıklar
Çağrılabilir bir 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ı
- İsteğe bağlı:
Authorization: Bearer <token>
- İstekte bulunan oturum açmış kullanıcı için bir Firebase Kimlik Doğrulama kullanıcı kimliği belirteci. Arka uç, bu belirteci otomatik olarak doğrular ve işleyicinin
context
kullanılabilir hale getirir. Belirteç geçerli değilse, istek reddedilir.
- İstekte bulunan oturum açmış kullanıcı için bir Firebase Kimlik Doğrulama kullanıcı kimliği belirteci. Arka uç, bu belirteci otomatik olarak doğrular ve işleyicinin
- İsteğe bağlı:
Firebase-Instance-ID-Token: <iid>
- Firebase istemci SDK'sından FCM kayıt belirteci. Bu bir dize olmalı. Bu, işleyicinin
context
kullanılabilir. Push bildirimlerini hedeflemek için kullanılır.
- Firebase istemci SDK'sından FCM kayıt belirteci. Bu bir dize olmalı. Bu, işleyicinin
- İsteğe bağlı:
X-Firebase-AppCheck: <token>
- İstekte bulunan istemci uygulaması tarafından sağlanan Firebase Uygulama Kontrolü belirteci. Arka uç, bu belirteci otomatik olarak doğrular ve işleyicinin
context
appId
enjekte ederek kodunu çözer. Belirteç doğrulanamazsa, istek reddedilir. (SDK >=3.14.0) için kullanılabilir
- İstekte bulunan istemci uygulaması tarafından sağlanan Firebase Uygulama Kontrolü belirteci. Arka uç, bu belirteci otomatik olarak doğrular ve işleyicinin
Başka başlıklar dahil edilirse, aşağıdaki yanıt belgelerinde açıklandığı gibi istek reddedilir.
Not: JavaScript istemcilerinde, bu istekler bir CORS OPTIONS
ön kontrolünü tetikler, çünkü:
-
application/json
izin verilmiyor.text/plain
veyaapplication/x-www-form-urlencoded
olmalıdır. -
Authorization
başlığı, CORS tarafından güvenli listelenmiş bir istek başlığı değildir. - Diğer başlıklara da benzer şekilde izin verilmez.
Çağrılabilir tetikleyici, bu OPTIONS
isteklerini otomatik olarak işler.
İstek gövdesi
HTTP isteğinin gövdesi, aşağıdaki alanlardan herhangi birine sahip bir JSON nesnesi olmalıdır:
- Gerekli:
data
- İşleve iletilen bağımsız değişken. Bu, herhangi bir geçerli 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.
İstekte başka alanlar varsa, arka uç, isteği hatalı biçimlendirilmiş olarak kabul eder ve reddedilir.
Yanıt formatı: durum kodları
Yanıttaki hatalar için farklı HTTP durum kodları ve dize durum kodları ile sonuçlanabilecek birkaç durum vardır.
client
tetikleyicisi çağrılmadan önce bir HTTP hatası olması durumunda, yanıt bir 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.İstemci tetikleyicisi çağrılır, ancak istek JSON olmaması, geçersiz alanların olması veya
data
alanının eksik olması gibi yanlış biçimdeyse, istekINVALID_ARGUMENT
hata koduyla400 Bad Request
ile reddedilir.İstekte sağlanan kimlik doğrulama belirteci geçersizse, istek
401 Unauthorized
ile veUNAUTHENTICATED
hata koduyla reddedilir.İstekte sağlanan FCM kayıt belirteci geçersizse, davranış tanımsızdır. Belirteç, FCM ile bir anında iletme bildirimi göndermek için kullanıldığı durumlar dışında her istekte kontrol edilmez.
Çağrılabilir tetikleyici çağrılır, ancak işlenmeyen bir istisna ile başarısız olur veya başarısız bir söz verirse, istek
INTERNAL
hata koduyla500 Internal Server Error
ile reddedilir. Bu, kodlama hatalarının yanlışlıkla son kullanıcılara maruz kalmasını önler.Çağrılabilir çağrılır ve çağrılabilir işlevler için sağlanan API kullanılarak 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 içinde tanımlandığı gibi, hata durumunun HTTP durumuyla resmi eşleştirilmesine dayanır. Döndürülen belirli hata kodu, ileti ve ayrıntılar, aşağıda ayrıntılı olarak açıklandığı gibi yanıt gövdesinde kodlanmıştır. Bu, işlev
OK
durumuyla açık bir hata döndürürse yanıtın200 OK
durumuna sahip olduğu, ancak yanıttaerror
alanının ayarlandığı anlamına gelir.İstemci tetiklemesi başarılıysa yanıt durumu
200 OK
.
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, herhangi bir isteğe bağlı alanla birlikte ya result
ya da error
içerir. Yanıt bir JSON nesnesi değilse veya data
veya error
içermiyorsa, istemci SDK'sı isteği, INTERNAL (13)
Google hata koduyla başarısız olarak değerlendirmelidir.
-
error
- Bu alan mevcutsa, HTTP durum koduna veyadata
de mevcut olup olmadığına bakılmaksızın isteğin başarısız olduğu kabul edilir. Bu alanın değeri,status
,message
ve (isteğe bağlı olarak)details
için alanlar içeren, hatalar için standart Google Cloud HTTP Eşleme biçiminde bir JSON nesnesi olmalıdır.code
alanı dahil edilmeyecektir.status
alanı ayarlanmamışsa veya geçersiz bir değerse, istemci, code.proto uyarınca durumuINTERNAL
olarak ele almalıdır.details
varsa, varsa, istemci SDK'sındaki hataya eklenen herhangi bir kullanıcı bilgisine dahil edilir.
Not: Buradakidetails
alanı, kullanıcı tarafından sağlanan bir değerdir. GoogleStatus
biçiminde olduğu gibi, proto türüyle anahtarlanmış bir değerler listesi olması gerekmez. -
result
- İşlev tarafından döndürülen değer. Bu, herhangi bir geçerli JSON değeri olabilir. Firebase-functions SDK, kullanıcı tarafından döndürülen değeri bu JSON formatına otomatik olarak kodlar. İstemci SDK'ları, aşağıda açıklanan serileştirme biçimine göre bu paramların kodunu yerel türlere otomatik olarak çözer.
Başka alanlar varsa, bunlar göz ardı edilmelidir.
seri hale getirme
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 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, bir float
ve bir 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 Any JSON kodlamasına ilişkin belgelere bakın.
Aşağıdaki türlere izin verilir:
- boş -
null
- int (imzalı veya imzasız, 32 bite kadar) - örneğin
3
veya-30
. - kayan nokta - örneğin
3.14
- çift - örneğin
3.14
- boole -
true
veyafalse
- dize - örneğin
"hello world"
- harita
- örneğin {"x": 3}
- liste
- örneğin [1, 2, 3]
- uzun (imzalı veya imzasız, 64 bite kadar) - [ayrıntılar için aşağıya bakın]
float
ve double
için NaN
ve Infinity
değerleri desteklenmez.
long
öğesinin normalde JSON'da izin verilmeyen özel bir tür olduğunu, ancak proto3 belirtiminde kapsandığını 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ı ayrılmış olarak kabul edilmeli ve geçirilen haritalar için kullanılmamalıdır.
Basit tipler için tip belirtilmediği için bazı değerler tel üzerinden geçtikten sonra tip değiştirecektir. Geçilen bir float
double
olur. short
, int
olur ve bu böyle devam eder. Android'de, liste değerleri için hem List
hem de JSONArray
desteklenir. Bu durumlarda, bir JSONArray iletmek bir List
verir.
@type
alanı bilinmeyen bir haritanın serisi kaldırılırsa, 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österir:
- Swift'de callable.call örneği
- Çağrı için bir başarı yanıtı
- Çağrı için bir başarısızlık yanıtı
Kodlamak için Swift'de 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"
}
}
}
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 organı:
{
"response": {
"aString": "some string",
"anInt": 57,
"aFloat": 1.23
}
}
Kodlama hatası 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"
}
}
}