Entegrasyon

Yükleme

Fotoğraflar, videolar ve sesli mesajlar için yükleme sağlayıcıları: Fivemanage, Fixitfy relay'i veya kendi sunucun.

Fotoğraflar, videolar, sesli mesajlar, profil fotoğrafları ve ilan görselleri bir yükleme sağlayıcısında saklanır. Veritabanı yalnızca bağlantıları tutar.

lua-- config_server.lua
ServerConfig.Upload.Provider = 'fivemanage'   -- 'fivemanage' | 'fmapi' | 'relay' | 'custom' | 'none'
Sağlayıcı Anahtar Dosya nasıl taşınır
fivemanage Fivemanage v3 API anahtarı Oyuncudan Fivemanage'e, presigned URL ile
fmapi Fivemanage v2 token'ı Oyuncudan Fivemanage'e, presigned URL ile
relay Yok (kendini kaydeder) Oyuncudan relay'in depolamasına, presigned URL ile
custom Servisinin header'ları Oyuncudan oyun sunucusuna küçük parçalar halinde, sonra sunucudan senin servisine
none Yüklemeler kapalı; kamera çalışır ama hiçbir şey kaydedilemez veya gönderilemez

Anahtarlar server tarafında, config_server.lua içinde kalır. Onları asla config.lua'ya ya da configs/ içindeki bir dosyaya koyma.

#Kabul edilen dosyalar

Tür Biçimler
Fotoğraflar image/jpeg, image/png, image/webp
Videolar video/webm, video/mp4
Ses audio/webm, audio/ogg, audio/mpeg, audio/wav

En büyük dosya boyutu Config.Limits.UploadBytes'tır (varsayılan 6 MiB). Oyun sunucusu üzerinden gönderilen dosyalar (presign olmadan custom sağlayıcı) 1 MiB ile sınırlıdır.

#Kontrol edilen bağlantılar

Bir yüklemeden sonra server, bağlantıyı kaydetmeden önce sağlayıcının host'unda olup olmadığını kontrol eder. Oyuncular telefona başka bir yere giden bir bağlantı kaydettiremez.

Oyuncuların yazdığı ya da yapıştırdığı bağlantılar ve script'lerin verdiği bağlantılar (fotoğraflar, avatarlar, ekler, ilan görselleri) etkin sağlayıcının host'unda ya da AllowedHosts içindeki bir host'ta olmalıdır:

luaAllowedHosts = { 'fivemanage.com', 'imgur.com', 'tenor.com', 'giphy.com' },   -- subdomains included
BlockedHosts = { 'cdn.discordapp.com', 'media.discordapp.net' },              -- wins over AllowedHosts

Bu görselleri diğer oyuncular yükler; bu yüzden liste bilinen host'larla sınırlıdır. Discord'un CDN'i engelli kalır, çünkü ek bağlantıları imzalıdır ve bir gün içinde süresi dolar; kaydedilen bir fotoğraf ertesi sabah bozulur. Oyuncular veya script'ler kendi görsel host'unu kullanıyorsa onu AllowedHosts'a ekle.

#Fivemanage v3

luaFivemanage = {
    Image = 'your-api-key',   -- one key is enough for every type
    Video = '',               -- optional separate keys
    Audio = '',
    CdnHost = '',             -- your custom Fivemanage CDN domain, e.g. 'cdn.myserver.com'
},
  1. Telefon, server'dan bir yükleme hakkı ister (tür, boyut, mime).
  2. Server, senin anahtarınla Fivemanage'den 60 saniye geçerli bir presigned URL ister.
  3. Telefon dosyayı bu URL'ye multipart alanı file olarak gönderir ve bağlantıyı yanıttan okur.
  4. Server bağlantıyı yalnızca r2.fivemanage.com veya senin CdnHost'un üzerindeyse kabul eder.

Dosyalar hiçbir zaman oyun sunucusundan geçmez. Presign başarısız olursa konsol [fx-phone:media] fivemanage presign failed: <reason> gösterir.

#Fivemanage v2

v3'ten önce oluşturulmuş token'lar için. v2 API'siyle aynı akış; multipart alanı dosya türüdür (image, video, audio).

luaProvider = 'fmapi',
FmApi = { Token = 'your-v2-token' },

#Fixitfy relay'i

luaProvider = 'relay',
Relay = { Url = 'https://relay.example.com', Key = '' },

Url, Fixitfy'ın sana verdiği relay adresidir. Resource ile birlikte bir anahtar gelmez:

  1. İlk yüklemede server, bir parmak izi (web_baseUrl convar'ın ya da resource KVP'sinde tutulan rastgele bir id), resource adı ve sürümüyle relay'e kendini kaydeder.
  2. Relay bir anahtarla yanıt verir; server onu resource KVP'sinde tutar.
  3. Yüklemeler relay'den bir presigned URL ister; oyuncu, dönen URL'ye yükler.
  4. Relay anahtarı reddederse server onu unutur ve bir sonraki yüklemede yeniden kaydolur.
  5. Reddedilen bir kayıt beklemeye geçer: 403 yanıtından sonra 6 saat, 429'dan sonra 1 saat, diğer durumlarda 15 dakika.

Key'i yalnızca Fixitfy sana bir anahtar verdiyse ayarla; o zaman olduğu gibi kullanılır ve kayıt yapılmaz.

#Özel sağlayıcı

luaProvider = 'custom',
Custom = {
    Url = 'https://upload.example.com/api/upload',
    Field = 'file',
    Headers = { Authorization = 'Bearer your-token' },
    Hosts = { 'cdn.example.com' },   -- when files are served from another host than Url
},

Server dosyayı Headers ile birlikte Field multipart alanı olarak gönderir ve bağlantıyı JSON yanıtında url, data.url, link, data.link, files.1.url, attachments.1.url alanlarından ilk bulunanda okur. Yalnızca Url'nin host'unda ya da Hosts içindeki bir host'ta bulunan https bağlantıları kabul edilir.

#Kendi servisinle presign

server/integrations/upload_custom.lua düzenlemeye açıktır. Oyuncuların doğrudan senin servisine yüklemesini sağlamak için CanPresign = true ayarla ve Presign(kind, bytes, mime) fonksiyonunun tek kullanımlık bir hedef döndürmesini sağla:

lua-- { url, method = 'PUT' | 'POST', headers?, fields?, fileField?, result?, publicUrl?, expires? }
function adapter.Presign(kind, bytes, mime)
    local status, body = Integration.Upload.Request('POST', 'https://upload.example.com/sign',
        json.encode({ kind = kind, bytes = bytes, mime = mime }),
        { Authorization = 'Bearer your-token', ['Content-Type'] = 'application/json' })
    local data = status == 200 and Integration.Upload.Json(body)
    if not data then return nil, ('sign answered %s'):format(status) end
    return { url = data.uploadUrl, method = 'PUT', headers = { ['Content-Type'] = mime }, publicUrl = data.publicUrl }
end
Alan Anlamı
url, method Oyuncunun dosyayı nereye ve nasıl gönderdiği
headers Bu istek için header'lar
fields, fileField Ek multipart alanları ve dosyanın alan adı. Ham bir PUT için fileField'ı yazma
result Bağlantının yanıttaki noktalı yolu, örneğin 'data.url'
publicUrl Önceden biliyorsan son bağlantı

Bu tablodaki her şeyi oyuncu görür. Asla uzun ömürlü bir token döndürme.

#Sorun giderme

Konsol Çözüm
uploads are off: ServerConfig.Upload.Provider "x" is not available Ad beş sağlayıcıdan biri değil
fivemanage presign failed: no API key in ServerConfig.Upload.Fivemanage Anahtarı ekle
fivemanage presign failed: presigned URL request answered 401 Anahtar yanlış ya da iptal edilmiş
player 12 finished upload ... with a URL that does not match fivemanage Özel bir CDN alan adı kullanılıyor; CdnHost'u ayarla
relay enrolment answered 403, retrying in 360 minutes Relay bu sunucuyu reddetti; Fixitfy ile iletişime geç
custom upload failed: no accepted URL in the reply Yanıtta izin verilen bir host'ta https bağlantısı yok; host'u Hosts'a ekle

Ayar başvurusu: config_server.lua. Medya export'ları: Medya export'ları.