API anahtarlarını yönetme

Open Cloud, API erişimini API anahtarları kullanarak kimlik doğrulaması ve yetkilendirme işlemlerini gerçekleştirir; bu anahtarlar, oyununuzda veri store'ları ve mekanlar gibi belirli kaynaklara erişmek ve bunları kullanmak için ayrıntılı izinler ve güvenlik kontrolü eklemenizi sağlar.

Tüm Open Cloud API'leri, geçerli izinlere sahip bir API anahtarı oluşturmanızı ve isteğinizde bir x-api-key başlığı eklemenizi gerektirir; bu, uygulamanın sizin adınıza Open Cloud'a kimlik doğrulaması yapmasını sağlar.

API anahtarları oluşturma

Kaynaklarınıza erişmek için API anahtarları oluşturabilir ve yapılandırabilirsiniz. Bir API anahtarının erişimi, onu sahip olan kullanıcının izinleri ile belirlenir. Bu, genellikle kullanıcının izinlerinin olduğu her kaynağa, bireysel oyunları dahil olmak üzere erişebileceği anlamına gelir ve grup sahipliğinde uygun bir role sahip olduğu oyunlar için de geçerlidir. Bazı kapsamlar belirli oyunlarla kısıtlanabilir, ancak hepsi değil.

Grup kaynaklarını yönetmek için API anahtarları oluşturma hakkında daha fazla bilgi için aşağıdaki Grup sahipliğindeki kaynakları yönetmek için API anahtarları oluşturma bölümüne bakın.

Bir API anahtarı oluşturmak için:

1. Creator Dashboard sayfasına gidin ve API Anahtarları sayfasını açın.

2. API Anahtarı Oluştur butonuna tıklayın.

3. API anahtarınız için benzersiz bir ad girin. Daha sonra amacınızı hatırlamanıza yardımcı olacak bir ad kullanın, örneğin, oyununuza mekanları yayınlarken PLACE_PUBLISHING_KEY.

4. Erişim İzinleri bölümünde, API Seç menüsünden bir API seçin. Anahtara birden fazla API eklemeniz gerekiyorsa bu adımı tekrarlayın.

5. Gerekli ise, API anahtarı ile erişmek istediğiniz oyunu seçin.

   İsteğe bağlı olarak Deneyimle Kısıtlama seçeneğini devre dışı bırakabilirsiniz. Devre dışı bırakıldığında, API anahtarınız kullanıcıya ait tüm oyunlara ve uygun izinlere sahip olduğunuz grup oyunlarına erişim sağlar; ayrıca gelecekte oluşturacağınız oyunlar için de geçerlidir.

6. Seçim İşlemleri açılır menüsünden API anahtarı için etkinleştirmek istediğiniz işlemleri seçin.

   API referansında çoğu işlem gerekli izin kapsamlarını içerir. Örneğin, bellek deposunu boşaltma işlemi universe.memory-store:flush iznini gerektirir.

   Tüm kapsamların ve destekledikleri API'lerin listesi için Kapsamlar sayfasına bakın.

7. (İsteğe bağlı) Güvenlik bölümünde, CIDR notasyonu kullanarak anahtara IP erişimini açıkça kısıtlayın. Yerel makinenizin IP adresini bulabilir ve bunu Kabul Edilen IP Adresleri bölümüne ekleyebilirsiniz; ayrıca erişime ihtiyaç duyan diğer IP adreslerini de ekleyebilirsiniz. Sabit bir IP adresiniz yoksa, ya da API anahtarını yalnızca yerel bir ortamda kullanıyorsanız, IP adreslerini kısıtla geçişini seçili bırakmamayı tercih edebilirsiniz.

8. (İsteğe bağlı): Kaynaklarınız için ek koruma sağlamak üzere anahtarınıza bir son tarih belirleyin.

9. Kaydet ve anahtar oluştur butonuna tıklayın.

10. API anahtarının dizesini güvenli bir konumda kopyalayın ve saklayın, kodunuzun halka açık bir deposunda değil.

11. API anahtarınızın durumunu Creator Dashboard 'ın API Uzantıları sayfasında kontrol edin.

Grup sahipliğindeki kaynakları yönetmek için API anahtarları oluşturma

Bir API anahtarı, kullanıcı hesabının izinleri olan tüm kaynaklara erişim sağlar, grup dışındaki kişisel oyunlar da buna dahildir. Eğer kişisel hesabınızdaki API anahtarını grup otomasyonu için kullanırsanız ve o anahtar tehlikeye girerse, erişebildiğiniz diğer kaynaklar da risk altındadır.

Bunu önlemek için, hedef gruba erişimi sıkı bir şekilde sınırlanmış ayrı bir API anahtarı oluşturmanızı şiddetle öneriyoruz. Otomasyon amaçlı bu yeni hesap yalnızca hedef gruba erişim sağlamak için oluşturulmalı ve görev doğrultusunda en az izinle donatılmalıdır.

1. Otomasyonunuz için yeni, özel bir Roblox hesabı oluşturun.
2. Yeni hesabı grubunuza davet edin.
3. Görevi için gerekli olan en az izinlere sahip bir grup rolü atayın (örneğin, yalnızca "Grup deneyimlerini oluştur ve düzenle").
4. Yeni hesabınıza giriş yapın ve yukarıdaki bölümdeki API anahtarı oluşturma adımlarını izleyin.
5. Oluşturulan API anahtarını grup kaynak otomasyonu için kullanın.

API Anahtarlarını Yönetme için En İyi Uygulamalar

API anahtarları, veri erişimini önlemek için güvenli bir şekilde saklanması gereken hassas kimlik bilgilerini içerir. İşte API anahtarlarını yönetmek için bazı en iyi uygulamalar.

• Her uygulama için ayrı anahtarlar oluşturun: Her uygulama veya kullanım durumu için ayrı API anahtarları oluşturun; bu, erişimi izole etmeye ve eğer bir anahtar tehlikeye girerse etkisini azaltmaya yardımcı olur.

• Gerekli minimum izinleri seçin: Kapsamları yapılandırırken, anahtarın amaçlanan kullanımı için gerekli en az izinleri seçin. İznin oyunla kısıtlanmasına izin veren alanlar varsa, yalnızca gerekli belirli oyunlara erişimi sınırlayın.

• IP adresi kısıtlamalarını kullanın: Bilinmeyen konumlardan yetkisiz kullanımını önlemek için API anahtarına erişimi özel IP adresleri veya CIDR aralıklarıyla kısıtlayın. API anahtarınızı Roblox mekanlarında kullanacağınız zaman IP adresi kısıtlamalarını kullanmayın; bu, anahtarınızın Roblox sunucularıyla kullanılmasını sağlar.

• Son tarih belirleyin: Kısa süreli kullanım durumları için, belirli bir süre sonra anahtarları otomatik olarak devre dışı bırakacak son tarihler belirleyin; böylece anahtar tehlikeye girerse riski azaltabilirsiniz. Uzun süreli kullanım durumları için son tarih belirlemek önerilmez, bunun yerine bir anahtar döngüleme süreciniz olduğunda son tarih belirlemek en iyisidir; çünkü anahtar süresi dolduğunda otomasyonunuz beklenmedik şekilde başarısız olabilir.

• Grup kaynak yönetimi için özel alternatif hesaplar kullanın: Grup sahipliğindeki kaynakları yönetmek için API anahtarları oluşturma bölümünde ayrıntılı olarak detaylandırıldığı gibi, grup kaynak yönetimi için en az izinlere sahip özel bir hesap kullanın.

• API anahtarlarını güvenli bir şekilde saklayın: API anahtarlarını asla doğrudan kaynak kodunuzda, sürüm kontrol sistemlerinde veya ifşa olabilecek betiklerde saklamayın. Anahtarlarınızı saklamak ve erişimini kontrol etmek için bir gizli yönetim sistemi kullanın. Roblox mekanlarında Gizli Depo kullanın.

• API anahtarlarını halka açık kanallar aracılığıyla paylaşmayın: API anahtarlarını asla halka açık iletişim kanalları, forumlar veya sosyal medya aracılığıyla paylaşmayın. Anahtarları yalnızca güvenilir ekip üyeleriyle özel, güvenli kanallar aracılığıyla paylaşın. Anahtarlarınızı kiminle paylaştığınızı sınırlayarak, bir anahtar tehlikeye girdiğinde etkisini en aza indirin.

CIDR formatı

Kaynaklarınızı daha fazla korumak için, bir API anahtarı oluşturma sırasında API anahtarına erişim sağlayabilecek IP adreslerini normal IP adresleri veya CIDR notasyonu kullanarak belirleyin. CIDR IP adresi, normal bir IP adresine benzer ancak sonunda bir eğik çizgi ve ağ yönlendirilmesi için önemli olan IP adresinin kaç bitinin önemli olduğunu gösteren bir ondalık ile biter:

• Normal: 192.168.0.0
• CIDR: 192.168.0.0/24

Öncelikli kısım IP adresidir ve son kısım ağ maskesidir, bu da ikili formatta 1'lerin bitlerini sayar. Önceki örnekte, 24 demek 255.255.255.0 (24 1'ler) demektir; bu da 192.168.0.0 ile 192.168.0.255 arasındaki tüm IP'lere izin verir. CIDR formatını anlamak, uygulamalarınızı bir sunucuda çalıştırmayı planlıyorsanız özellikle yararlıdır.

API anahtarının durumu

API anahtarları başlangıçta aktif bir duruma sahiptir, ancak yaşamları boyunca devre dışı kalabilirler. Bir API anahtarının durumunun neden değiştiğini ve API anahtarını nasıl aktif duruma döndüreceğinizi öğrenmek için aşağıdaki tabloya bakın.

API anahtarlarını inceleme

POST api-keys/v1/introspect

Bir API anahtarı hakkında bilgi alın. Anahtarın talep edenin IP adresinden kullanılıp kullanılamayacağını ve anahtarın veya en son oluşturulan kullanıcının denetim altında olup olmadığını doğrular.

İstek

(application/json)

Örnek İnceleme API Anahtar İsteği
curl --location --request POST 'https://apis.roblox.com/api-keys/v1/introspect' \
--header 'Content-Type: application/json' \
--data '{
    "apiKey": "your-api-key"
}'

Cevap

Her kapsam nesnesinde bulunabilecek dört olası kaynak tanımlayıcısı vardır:

• userId
• groupId
• universeId
• universeDatastore

userId ve groupId tanımlayıcıları yalnızca yaratıcı hedefli kapsamlarla ilgilidir. universeDatastore tanımlayıcısı yalnızca universe-datastore hedefli kapsamlarla ilgilidir. Kaynak tanımlayıcısı, kaynak seçimini desteklemeyen kapsamlar için atlanacaktır.

Kaynak tanımlayıcı listesinde bir yıldız (*), kapsamın o türdeki tüm kaynaklar üzerinde izni olduğunu gösterir.

Örnek İnceleme API Anahtar Cevabı
{
  "name": "test key",
  "authorizedUserId": 234,
  "scopes": [
    {
      "name": "universe-datastores.objects",
      "operations": [
        "create"
      ],
      "universeDatastores": [
        {
          "universeId": "123",
          "datastoreName": "playerData"
        }
      ]
    },
    {
      "name": "asset",
      "operations": [
        "write"
      ],
      "groupIds": [
        "*"
      ],
      "userIds": [
        "*"
      ]
    }
  ],
  "enabled": true,
  "expired": false,
  "expirationTimeUtc": "2026-01-01T12:00:00.000Z"
}