Spesifikasi protokol untuk https.onCall

Pemicu https.onCall untuk Cloud Functions adalah pemicu HTTPS dengan format khusus untuk permintaan dan respons. Artikel ini menjelaskan spesifikasi format permintaan dan respons HTTPS yang digunakan oleh SDK klien untuk mengimplementasikan API. Informasi ini mungkin berguna bagi Anda jika kebutuhan Anda tidak dapat dipenuhi menggunakan SDK Android, iOS, atau web.

Format permintaan: header

Permintaan HTTP ke sebuah endpoint pemicu callable harus berupa POST dengan header berikut:

  • Wajib: Content-Type: application/json
    • Opsional ; charset=utf-8 diperbolehkan.
  • Opsional: Authorization: Bearer <token>
    • Token ID pengguna Firebase Authentication untuk pengguna yang login dan membuat permintaan. Backend secara otomatis memverifikasi token ini dan menyediakannya di context pengendali. Jika token tidak valid, permintaan akan ditolak.
  • Opsional: Firebase-Instance-ID-Token: <iid>
    • Token ID Instance dari SDK klien Firebase. Harus berupa string dan tersedia dalam context penangan. Token ini sangat berguna untuk mengirim notifikasi push.

Jika ada header lain yang disertakan, maka permintaan akan ditolak, seperti yang dijelaskan dalam dokumentasi respons di bawah.

Catatan: Pada klien JavaScript, permintaan ini memicu preflight OPTIONS CORS, karena:

Pemicu callable menangani permintaan OPTIONS ini secara otomatis.

Isi permintaan

Isi permintaan HTTP harus berupa objek JSON dengan salah satu kolom berikut:

  • Wajib: data - Argumen yang diteruskan ke fungsi. Nilai ini dapat berupa sembarang nilai JSON yang valid. Nilai otomatis didekode ke dalam jenis JavaScript native sesuai dengan format serialisasi yang dijelaskan di bawah.

Jika ada kolom lain yang ada dalam permintaan, backend akan menganggap permintaan menggunakan format yang salah, dan akan ditolak.

Format respons: kode status

Ada beberapa kasus yang dapat menghasilkan kode status HTTP berbeda dan kode status string untuk error dalam respons.

  1. Dalam kasus error HTTP sebelum pemicu client dipanggil, respons tidak ditangani sebagai fungsi klien. Misalnya, jika klien mencoba memanggil fungsi yang tidak ada, respons 404 Not Found akan diterima.

  2. Jika pemicu klien dipanggil, tetapi format permintaannya salah, misalnya tidak menggunakan format JSON, memuat kolom yang tidak valid, atau kolom data tidak ada, permintaan akan ditolak dengan 400 Bad Request, dengan kode error INVALID_ARGUMENT.

  3. Jika token autentikasi yang dimasukkan ke dalam permintaan tidak valid, permintaan akan ditolak dengan 401 Unauthorized, dengan kode error UNAUTHENTICATED.

  4. Jika token ID Instance yang dimasukkan ke dalam permintaan tidak valid, perilaku tidak dapat ditentukan. Token ID Instance tidak diperiksa pada setiap permintaan, kecuali saat digunakan untuk mengirim notifikasi push dengan FCM.

  5. Jika pemicu callable dipanggil, tetapi gagal dengan pengecualian yang tidak tertangani atau menampilkan promise yang gagal, permintaan akan ditolak dengan 500 Internal Server Error, dengan kode error INTERNAL. Hal ini mencegah ditampilkannya error coding ke pengguna akhir secara tidak sengaja.

  6. Jika callable dipanggil dan menampilkan condition error eksplisit menggunakan API yang disediakan untuk fungsi callable, maka permintaan akan gagal. Kode status HTTP yang ditampilkan didasarkan pada pemetaan resmi status error ke status HTTP, seperti yang ditentukan dalam code.proto. Kode error, pesan, dan detail spesifik yang ditampilkan akan dienkode dalam isi respons seperti dijelaskan di bawah. Ini berarti bahwa jika fungsi ini menampilkan error eksplisit dengan status OK, maka respons akan memiliki status 200 OK, tetapi kolom error ditetapkan dalam respons.

  7. Jika pemicu klien berhasil, status responsnya adalah 200 OK.

Format respons: header

Respons memiliki header berikut:

  • Content-Type: application/json
  • Opsional ; charset=utf-8 diperbolehkan.

Isi respons

Respons dari endpoint klien selalu berupa objek JSON. Respons ini harus memuat kolom data atau error, beserta kolom opsional. Jika respons tidak berupa objek JSON, atau tidak memuat kolom data atau error, SDK klien harus menganggap permintaan tersebut gagal dengan kode error Google INTERNAL (13).

  • error - Jika kolom ini ada, maka permintaan dianggap gagal, terlepas dari kode status HTTP atau apakah kolom data ada atau tidak. Nilai kolom ini harus berupa objek JSON dalam format Pemetaan HTTP Google Cloud standar untuk error, dengan kolom untuk status, message, dan details (opsional). Kolom code tidak perlu disertakan. Jika kolom status tidak ditetapkan, atau merupakan nilai yang tidak valid, klien harus menganggap statusnya sebagai INTERNAL, sesuai dengan code.proto. Jika details ada, kolom ini akan disertakan dalam info pengguna yang ditambahkan ke error dalam SDK klien, jika berlaku.
    Catatan: Kolom details di sini adalah nilai yang diisi oleh pengguna. Nilai ini tidak harus berupa daftar nilai yang diketikkan oleh jenis proto seperti dalam format Status Google.
  • data - Nilai yang ditampilkan oleh fungsi. Nilai ini dapat berupa sembarang nilai JSON yang valid. Firebase Functions SDK secara otomatis mengenkode nilai yang ditampilkan oleh pengguna ke dalam format JSON ini. SDK klien mendekode parameter ini ke dalam jenis native secara otomatis, sesuai dengan format serialisasi yang dijelaskan di bawah.

Jika kolom lain ada, maka kolom tersebut harus diabaikan.

Serialisasi

Serialisasi untuk payload data arbitrer menggunakan format yang sama baik untuk permintaan maupun respons.

Untuk konsistensi platform, payload dienkode ke dalam JSON seolah-olah merupakan nilai dari kolom Any dalam buffer protokol proto3, menggunakan pemetaan JSON standar. Nilai berjenis sederhana seperti null, int, double, atau string dienkode langsung, dan tidak menyertakan jenis eksplisitnya. Jadi, float dan double dienkode dengan cara yang sama, dan Anda mungkin tidak tahu nilai mana yang akan diterima di ujung lain panggilan. Untuk jenis yang bukan native JSON, encoding proto3 yang diketikkan untuk nilai itu akan digunakan. Untuk informasi lebih lanjut, lihat dokumentasi untuk encoding JSON mana saja.

Jenis-jenis berikut diizinkan:

  • null - null
  • int (ditandatangani atau tidak, hingga 32 bit) - misalnya 3 atau -30.
  • float - misalnya 3.14
  • double - misalnya 3.14
  • boolean - true atau false
  • string - misalnya "hello world"
  • map - misalnya {"x": 3}
  • list - misalnya [1, 2, 3]
  • long (ditandatangani atau tidak, hingga 64 bit) - [lihat detailnya di bawah]

Nilai NaN dan Infinity untuk float dan double tidak didukung.

Harap diperhatikan bahwa long adalah jenis khusus yang biasanya tidak diizinkan di JSON, tetapi dicakup oleh spesifikasi proto3. Misalnya, long berikut ini dienkode sebagai:

long

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

long tidak ditandatangani

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

Secara umum, kunci @type harus dianggap dicadangkan, dan tidak digunakan untuk map yang diterima.

Karena jenis ini tidak ditentukan untuk nilai berjenis sederhana, beberapa nilai akan berubah jenis setelah diteruskan. Nilai float yang diterima akan menjadi double. Nilai short akan menjadi int, dan sebagainya. Pada Android, List dan JSONArray didukung untuk nilai daftar. Dalam hal ini, meneruskan JSONArray akan menghasilkan List.

Jika deserialisasi dilakukan pada map dengan kolom @type yang tidak dikenal, maka map akan dibiarkan apa adanya. Dengan begitu developer dapat menambahkan kolom berjenis baru ke nilai yang ditampilkan tanpa membobol klien yang lebih lama.

Contoh kode

Contoh dalam bagian ini menggambarkan cara mengenkode berikut ini:

  • Contoh callable.call di Swift
  • Respons sukses untuk panggilan
  • Respons kegagalan untuk panggilan

Contoh callable.call di Swift untuk dienkode

callable.call([
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23,
    "aLong": -123456789123456 as Int64
])

Header permintaan:

Method: POST
Content-Type: application/json; charset=utf-8
Authorization: Bearer some-auth-token
Firebase-Instance-ID-Token: some-iid-token

Isi permintaan:

{
    "data": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23,
        "aLong": {
            "@type": "type.googleapis.com/google.protobuf.Int64Value",
            "value": "-123456789123456"
        }
    }
}

Respons untuk dienkode

return {
    "aString": "some string",
    "anInt": 57,
    "aFloat": 1.23
};

Header respons yang berhasil:

200 OK
Content-Type: application/json; charset=utf-8

Isi respons yang berhasil:

{
    "data": {
        "aString": "some string",
        "anInt": 57,
        "aFloat": 1.23
    }
}

Respons kegagalan untuk dienkode

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

Header respons yang gagal:

401 UNAUTHENTICATED
Content-Type: application/json; charset=utf-8

Isi respons yang gagal:

{
    "error": {
        "message": "Request had invalid credentials.",
        "status": "UNAUTHENTICATED",
        "details": {
            "some-key": "some-value"
        }
    }
}

Kirim masukan tentang...

Butuh bantuan? Kunjungi halaman dukungan kami.