REST API ile sosyal medya gönderilerini zamanla

Adımların tamamı

Mellow Hub üzerinden bir gönderi zamanlamak için kimlik bilgisinin hangi yetkilere sahip olduğunu belirle, bağlı kanalları seç, tek bir isteği doğrula, ardından onu sabit bir idempotency anahtarıyla oluştur. Her hedefte ne olduğunu netleştirmek için oluşan gönderiyi yeniden oku. Başarılı bir oluşturma yanıtı, her ağın gönderiyi yayınladığının kanıtı değildir.

Bu tarif REST kullanır. Bir MCP istemcisi eşdeğer whoami → list_channels → validate_post → create_post → get_post sırasını izler; bu sıra sosyal medya MCP rehberinde anlatılır.

Girdi kontrolünü çalıştırmaya hazır bir örnekle dene

Aynı klasöre Node.js girdi kontrol aracını ve post.example.json şablonunu indir. Betik, Node.js 22 ya da daha yeni bir sürüm gerektirir; paket kurmana gerek yoktur. Kaynak kodunu oku, ardından mevcut bir Hub kimlik bilgisini gizli ortam değişkenlerinde MELLOW_HUB_KEY olarak tanımla.

Bu kontrol için channels:read ve posts:read yeterlidir. Hub’ın erişim ayarlarında yalnızca kullanmayı düşündüğün kanalları seç. Kanalları listelemek için yalnızca ilk izin gerekir. Bu girdi kontrolü için yayın izni ya da abonelik gerekmez.

node mellow-hub-check.mjs --channels
# post.example.json içindeki kanal kimliklerini ve medya URL’sini değiştir.
node mellow-hub-check.mjs post.example.json

Betik, kimlik bilgisinin erişebildiği kanalları kontrol eder, düzenlediğin JSON dosyasını kimlik bilgisiyle Mellow Hub’ın doğrulama uç noktasına gönderir ve engelleyici sorunlarla notları ekrana yazdırır. Girdi kontrolleri başarılı olursa 0, girdi sorunu varsa 1, dosya, izin, bağlantı ya da beklenmeyen yanıt hatasında 2 koduyla çıkar. HTTP 200 yanıtında ok: false varsa kontrol yine başarısız sayılır.

Betik gönderi oluşturmaz, medya indirmez ve hiçbir sosyal ağa istek göndermez. Bu kontrolden geçmek şunları doğrulamaz: dosya süresi, en boy oranı, hesabın nihai yetkilendirmesi ya da yayın. İndirilebilir kod, yalıtılmış test verileriyle kontrol edildi; bu, kayda alınmış canlı bir müşteri yayını değildir. Aşağıdaki curl istekleri için düzenlediğin dosyayı post.json olarak kaydet.

1. Hesabı ve kimlik bilgisini kontrol et

Kendi kanallarını Hub’da bağla ve devretmek istediğin kanallar ile modla bir kimlik bilgisi oluştur. Bunu sunucunun gizli ortam değişkenlerinde MELLOW_HUB_KEY olarak sakla; asla frontend JavaScript koduna ya da herkese açık bir depoya koyma. Örnekler bu ortam değişkenini, değerini göstermeden okur.

curl --fail-with-body https://www.mellow.world/api/hub/v1/whoami \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

curl --fail-with-body https://www.mellow.world/api/hub/v1/channels \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

Bu hesap için dönen kanal kimliklerini kullan. Aşağıdaki spc_… değerleri yer tutucudur. Bir şey oluşturmadan önce modu ve kullanılabilir kotayı kontrol et. İnceleme modundaki bir kimlik bilgisi, gönderiyi bir kişinin onayına hazırlar. Otomatik pilot modundaki bir kimlik bilgisi ise devredilen kapsam, üst sınır ve geçerlilik süresi içinde işlem yapabilir.

2. Gerçek gönderiyi tanımla

Aşağıdaki yapıyı post.json olarak kaydet. İki kanal kimliğini, örnek medya adresini, metni ve örnek tarihi değiştir. Açıkça belirtilmiş bir ISO 8601 saat dilimi farkı ya da UTC Z işareti kullan; zaman damgası okuyucunun yerel saatini değil, belirli bir anı temsil eder. Örnekteki 2030 tarihi bilerek örnek amaçlı seçildi.

{
  "caption": "A short look at how this piece was made.",
  "channels": [
    "spc_your_instagram_channel",
    "spc_your_youtube_channel"
  ],
  "media": [
    "https://cdn.example.com/your-video.mp4"
  ],
  "scheduledAt": "2030-01-15T10:00:00Z",
  "options": {
    "instagram": {
      "placement": "reels"
    },
    "youtube": {
      "title": "How this piece was made",
      "privacyStatus": "public"
    }
  }
}

Ağ medyayı yayın anında çeker; bu yüzden gerçek HTTPS URL’si o anda da erişilebilir olmalıdır. Özel bir yerel dosya ya da süresi dolmuş imzalı bir URL işe yaramaz. Bu örnek, YouTube’a ayrı bir başlık verirken Instagram için Reels yerleşimini seçer. Formatların kullanılabilirliği yine bağlı hesaplarına ve sağlayıcıya göre değişir.

3. Yayınlamadan doğrula

curl --fail-with-body https://www.mellow.world/api/hub/v1/validate \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @post.json

Yanıttaki ok, issues ve notes alanlarını incele. Devam etmeden önce engelleyici sorunların hepsini düzelt. Doğrulama, ok: false ile birlikte HTTP 200 döndürebilir; bu yüzden yalnızca HTTP durum koduna bakmak yeterli değildir. Kimlik bilgisiyle çağrılan uç nokta, girdi kurallarının yanı sıra kanalların gerçekten sana ait olup olmadığını da kontrol eder.

Açıklama, başlık ve medya sayısı kontrollerini hesap gerektirmeden önizlemek için ücretsiz gönderi kontrol aracını kullan. İki önizleme de gerçek dosyanın süresini ya da en boy oranını ölçmez; sağlayıcı da teslimi yine reddedebilir.

4. Bir kez oluştur, tutarlı biçimde yeniden dene

Başlangıçtaki salt okunur kimlik bilgisi gönderi oluşturamaz. Bu adımdan önce, hedeflenen kanallar için posts:write ve posts:publish izinlerine sahip bir bağlantı kullan. Bu kapsamlar inceleme modunda da gerekir; yine de bu modda yayınlama kararını bir insan verir. Bu izinler olmadan istek bir izin hatası döndürür.

Sonraki istek gönderiyi oluşturur. Onu yalnızca içerik ve hedefler üzerindeki yetki doğruysa çalıştır. İnceleme modunda gönderi onay bekler; otomatik pilotta devredilen işlem zamanlanan saatte gerçekleşebilir.

curl --fail-with-body https://www.mellow.world/api/hub/v1/posts \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: studio-process-video-slot-001" \
  --data-binary @post.json

Idempotency anahtarını uygulamanda ilgili işle birlikte kalıcı olarak sakla. Yanıt kaybolursa aynı isteği aynı anahtarla yeniden dene. Yalnızca zaman aşımı oldu diye yeni bir anahtar oluşturma. Farklı bir gönderi farklı bir anahtar gerektirir; bir anahtarı değiştirilmiş içerikle yeniden kullanma girişimleri reddedilir.

5. Sonucu her hedef için ayrı oku

Dönen post.id değerini kaydet ve aynı yetkilendirme başlığını kullanarak GET /api/hub/v1/posts/{id} ile gönderiyi getir. targets içindeki her kaydı ve herkese açık URL’sini incele. Birden fazla ağa giden bir gönderi kısmi olabilir: bir hedef başarılı olurken bir diğeri başarısız olabilir.

Planlanan saati, Hub gönderi kimliğini, idempotency anahtarını ve hedef sonuçlarını kendi iş kaydında bir arada tut. Kimlik bilgilerini ya da yetkilendirme başlıklarının tamamını günlüğe yazmaktan kaçın. Bir hedef başarısız olduğunda, gönderinin tamamını körü körüne yeniden oluşturmak yerine bildirilen hataya bakarak sonraki adıma karar ver.

Zaman aşımına uğrayan ya da kısmen yayınlanan bir gönderiyi kurtar

Zaman aşımı, isteği gönderen tarafın sonucu bilmediği anlamına gelir. partial sonucu ise Hub’ın seçili hedefler için farklı sonuçlar kaydettiği anlamına gelir. Bundan sonra ne göndereceğine karar verirken bu durumları birbirinden ayrı tut.

Oluşturma yanıtı kayboldu

İlk istekten önce özgün istek gövdesini ve idempotency anahtarını iş kaydında sakla. Değiştirmediğin bu isteği aynı anahtarla ve geçerli bir yetkiyle yeniden dene. Gönderi Hub’da zaten varsa Hub o gönderinin kimliğini ve güncel durumunu döndürür. REST yanıtı yine HTTP 201 olur; bu yüzden tek başına 201 kodu, bu denemenin yeni bir kayıt oluşturup oluşturmadığını söylemez. Kimliği aldıktan sonra durumunu GET ile takip et.

Yanıt olarak 409 idempotency_key_reused alırsan isteği kaydettiğin işle karşılaştır. Hatayı aşmak için otomatik olarak başka bir anahtar üretme: bu yeni bir işlem anlamına gelir ve özgün yayının yinelenmesine yol açabilir.

Bir hedef yayınlandı, diğeri başarısız oldu

Kurtarma hazırlamadan önce targets alanını oku. Örneğin Instagram published, YouTube ise failed durumundaysa bildirilen YouTube sorununu düzelt ve yalnızca o YouTube kanalını içeren yeni bir istek gövdesini doğrula. Bilinçli bir kurtarma, studio-process-video-slot-001-youtube-recovery-1 gibi yeni bir anahtar kullanır. Yeni gönderi kimliğini özgün işin yanında sakla. Olağan kanal izinleri, inceleme modu ve yayın kotası yine geçerlidir.

Özgün anahtarla isteği yeniden göndermek mevcut gönderiyi döndürür; başarısız hedeflerini yeniden başlatmaz. Hâlâ bekleyen ya da yayınlanmakta olan bir hedef, doğrulanmış bir başarısızlık değildir. Yalnızca isteği gönderen taraf beklemeyi bıraktı diye o hedefe yeniden gönderme; zaten yayınlanmış hedefleri de kurtarma isteğine ekleme.

Gerçek entegrasyonlarda sorulan sorular

Bir ağda farklı bir açıklama kullanabilir miyim?

Evet. Gerçek kanal kimliğini anahtar olarak kullanan bir perChannel kaydı, o kanalın açıklamasını ya da medyasını geçersiz kılar. Platform genelindeki alanlar options içine yazılır. Çözümlü örnekler için Hub referansına bak.

Bir ajan sosyal hesaplarımı kendi başına bağlayabilir mi?

Hayır. İlgili bağlantı akışını hesap sahibi tamamlar. API anahtarı, zaten yetkilendirilmiş işlemler için bir yetki devridir; bir ağın giriş ekranında hesap sahibinin yerine geçme izni değildir.

Tek bir istek planımdan tek bir yayın mı kullanır?

Kota, ağdaki her hedef için ayrı ayrı sayılır. Hedefleri seçmeden önce güncel planlara ve kimlik bilgisinin kalan kotasına göz at.