WordPress 7.0 ile gelen WordPress Connectors API, bir sitenin harici servis bağlantılarını ortak bir kayıt sistemi ve tek yönetim ekranı üzerinden düzenler. İlk sürümün odağı yapay zekâ sağlayıcılarıdır. Bu nedenle API’yi Stripe, CRM veya e-posta servisleri için hazır bir istek katmanı gibi düşünmek hatalıdır. Connectors API; bağlantı meta verisini, API anahtarının kaynağını ve ilişkili sağlayıcı eklentisini yönetir. Servise gerçek isteği ise ilgili sağlayıcı eklentisi ya da WP AI Client yapar.
Bu rehberde WordPress Connectors API ile çalışırken kullanacağınız gerçek fonksiyonları ve kayıt yaşam döngüsünü ele alıyoruz.
Bu rehber; WordPress 7.0’daki gerçek işlevleri, wp_connectors_init yaşam döngüsünü, kayıt verisinin biçimini ve kimlik bilgisi önceliğini çalışan PHP örnekleriyle açıklar. Ayrıca veritabanında tutulan anahtarların şifrelenmediği gerçeğini ve plugin.slug yerine neden plugin.file kullanılması gerektiğini gösterir.
Connectors API’nin gerçek kapsamı ve bileşenleri
Bir connector, harici servisin kendisi değildir. WordPress’e o servis hakkında standart meta veri veren bir kayıt girdisidir. Girdide görünen ad, açıklama, logo, connector türü, kimlik doğrulama yöntemi ve isteğe bağlı eklenti dosyası bulunur.
WordPress 7.0; Anthropic, Google ve OpenAI için öne çıkan connector tanımlarıyla gelir. WP AI Client’ın varsayılan registry’sine kayıt yapan sağlayıcı eklentileri otomatik keşfedilir. Dolayısıyla uyumlu bir AI sağlayıcısı için ikinci kez connector kaydı yazmak gerekmez.
Connectors ekranı Türkçe yönetim panelinde Ayarlar → Connectors yolundadır. Kartlar şu verileri kullanır:
name,descriptionvelogo_url: Kartın görünen içeriği.type: Connector sınıfı; AI sağlayıcılarındaai_provider.authentication:api_keyveyanoneyöntemi ve anahtar ayarları.plugin.file: Eklentininwp-content/pluginsdizinine göre ana dosya yolu.authentication.credentials_url: Anahtar alınacak sağlayıcı sayfası.
Aşağıdaki kayıt, resmi veri biçimine uygun özel bir AI connector örneğidir:
add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) {
$registry->register(
'kurum-ai',
array(
'name' => 'Kurum AI',
'description' => 'Şirket içi üretken yapay zekâ sağlayıcısı.',
'logo_url' => plugins_url( 'assets/logo.svg', __FILE__ ),
'type' => 'ai_provider',
'authentication' => array(
'method' => 'api_key',
'credentials_url' => 'https://ai.example.com/account/keys',
'setting_name' => 'connectors_ai_kurum_ai_api_key',
'env_var_name' => 'KURUM_AI_API_KEY',
'constant_name' => 'KURUM_AI_API_KEY',
),
'plugin' => array(
'file' => 'kurum-ai-provider/kurum-ai-provider.php',
),
)
);
} );Connector kimliği yalnızca küçük harf, rakam, alt çizgi ve tire içerebilir. kurum-ai geçerlidir; Kurum AI geçersizdir. WordPress aynı kimliğin ikinci kez kaydedilmesini de reddeder.
API anahtarı nasıl bulunur ve güvenli yapılandırılır?
WordPress Connectors API kimlik doğrulama değerini connector meta verisine göre çözer. Öncelik sırası değişmez:
- Ortam değişkeni
- PHP sabiti
- Yönetim ekranında kaydedilen veritabanı ayarı
Örneğin KURUM_AI_API_KEY ortam değişkeni varsa aynı adlı PHP sabiti ve veritabanındaki değer kullanılmaz. Bu davranış, üretim anahtarını koddan ve veritabanından uzak tutmayı kolaylaştırır.
Sunucunun ortam değişkeni desteği yoksa wp-config.php içinde, “Düzenlemeyi bırakın” satırından önce sabit tanımlanabilir:
define( 'KURUM_AI_API_KEY', 'gercek-anahtari-buraya-yazin' );Ardından kayıt içindeki constant_name alanının aynı adı taşıması gerekir. AI sağlayıcılarında varsayılan adlandırma {PROVIDER_ID}_API_KEY biçimindedir. Diğer connector türlerinde env_var_name ve constant_name ayrıca belirtilebilir.
Önemli güvenlik sınırı şudur: Yönetim ekranından girilen API anahtarları veritabanında maskelenir fakat WordPress 7.0’ın ilk sürümünde şifrelenmez. Ayrıca sitede çalışan üçüncü taraf PHP kodu, connector değerine erişebilir. Bu nedenle:
- Sağlayıcı panelinde en düşük gerekli yetkilere sahip ayrı bir anahtar oluşturun.
- Geliştirme ve üretim ortamlarında farklı anahtarlar kullanın.
- Kullanım kotası ve fatura uyarılarını sağlayıcı tarafında etkinleştirin.
- Kullanılmayan anahtarları silin; düzenli anahtar rotasyonu uygulayın.
- Veritabanı yerine, mümkünse ortam değişkeni kullanın.
Gerçek projelerde en sık görülen sorun, anahtarın Ayarlar ekranına girildiği hâlde eski bir ortam değişkeninin etkin kalmasıdır. WordPress ortam değişkenini önce okuduğu için arayüzdeki yeni değer sonucu değiştirmez. Tanı koyarken üç kaynağı da aynı sırayla kontrol etmek gerekir.
Connector kayıtlarını PHP ile sorgulama
WordPress Connectors API kayıtları init sırasında hazırlanır. Kayıt tamamlandıktan sonra üç public fonksiyon kullanılabilir: wp_is_connector_registered(), wp_get_connector() ve wp_get_connectors(). Registry singleton’ına doğrudan erişmek yerine bu fonksiyonlar tercih edilmelidir.
Belirli bir sağlayıcının kullanılabilir olup olmadığını kontrol eden örnek:
add_action( 'init', function () {
if ( ! wp_is_connector_registered( 'anthropic' ) ) {
return;
}
$connector = wp_get_connector( 'anthropic' );
error_log(
sprintf(
'Connector: %s | Tür: %s',
$connector['name'],
$connector['type']
)
);
} );Tüm kayıtları listelemek için:
add_action( 'admin_notices', function () {
if ( ! current_user_can( 'manage_options' ) ) {
return;
}
foreach ( wp_get_connectors() as $id => $connector ) {
printf(
'<p><code>%s</code>: %s</p>',
esc_html( $id ),
esc_html( $connector['name'] )
);
}
} );Bu fonksiyonlar bağlantı üzerinden doğrudan prompt göndermez veya ödeme başlatmaz. Örneğin bir AI modeline istek göndermek için WP AI Client kullanılır. Connectors API o istemcinin hangi sağlayıcı yapılandırmasına erişebileceğini destekleyen platform katmanıdır.
Kayıt yaşam döngüsü
WordPress init aşamasında önce yerleşik connector tanımlarını yükler. Sonra AiClient::defaultRegistry() içindeki sağlayıcıları keşfeder ve meta verilerini birleştirir. En son wp_connectors_init aksiyonu çalışır. Eklentiler yalnızca bu aksiyon içinde kayıt eklemeli veya değiştirmelidir.
Bir kaydın açıklamasını değiştirmek için aynı kimliği yeniden kaydetmek işe yaramaz. Doğru desen; varlığı kontrol etmek, kaydı kaldırmak, diziyi değiştirmek ve tekrar kaydetmektir:
add_action( 'wp_connectors_init', function ( WP_Connector_Registry $registry ) {
if ( ! $registry->is_registered( 'anthropic' ) ) {
return;
}
$connector = $registry->unregister( 'anthropic' );
$connector['description'] = 'Kurumsal içerik akışında kullanılan sağlayıcı.';
$registry->register( 'anthropic', $connector );
} );Varlık kontrolü yapılmadan unregister() çağrılırsa _doing_it_wrong() bildirimi oluşur. Ayrıca bu değişiklik yalnızca çalışma zamanındaki registry’yi etkiler; sağlayıcı eklentisinin kaynak kodunu değiştirmez.
Harici servis entegrasyonunda doğru mimari
Connectors API’nin ilk odağı AI sağlayıcıları olsa da registry farklı connector türlerini kabul eder. Ancak api_key dışındaki yöntemler için tam yönetim arayüzü hazır değildir. Özel OAuth ekranı veya servis çağrısı gerekiyorsa bunu eklenti kodu sağlamalıdır.
Sağlıklı bir eklenti mimarisi üç katmana ayrılabilir:
- Connector kaydı: Ad, tür, logo, kimlik doğrulama ve eklenti meta verisi.
- Sağlayıcı istemcisi: HTTP isteğini oluşturan, yanıtı ayrıştıran ve hata kodlarını ele alan sınıf.
- İş özelliği: İçerik özeti, görsel üretimi veya başka bir kullanıcı işlevi.
Bu ayrım sayesinde yönetici WordPress Connectors API ekranından bağlantıyı kurar; eklenti ise connector varlığını denetledikten sonra kendi istemcisini çalıştırır. Bir ödeme servisi için yalnızca connector kaydı oluşturmak, ödeme API’sini otomatik olarak WordPress’e kazandırmaz.
Özel bağlantı eklerken şu kontrol listesini kullanın:
- Connector kimliğini kararlı ve küçük harfli seçin.
plugin.filedeğerini eklentinin gerçek ana dosyasına göre yazın.- Anahtar kaynağı için ortam değişkenini önceliklendirin.
- Servis isteğini connector registry kodundan ayırın.
wp_connectors_initdışında kayıt değiştirmeyin.- Yönetim ekranında bağlantı durumunu ve anahtar kaynağını doğrulayın.
- Sağlayıcı tarafında kota, kapsam ve iptal seçeneklerini test edin.
Sık karşılaşılan hatalar ve teşhis adımları
Connector kartı görünmüyor
Önce wp_is_connector_registered( 'connector-id' ) sonucunu loglayın. Sonuç false ise aksiyon adı, eklenti etkinliği ve kimlik biçimini kontrol edin. plugin.slug kullanan eski bir örnek kopyalandıysa bunu plugin.file ile değiştirin. WordPress 7.0’ın güncel biçiminde yanlış eklenti meta verisi sessizce atılabilir.
API anahtarı değiştiği hâlde eski bağlantı kullanılıyor
Ortam değişkeni, PHP sabiti ve veritabanı sırasını inceleyin. Üst sıradaki değer alt sıradakini gölgeler. Bu durum özellikle hosting panelinde daha önce tanımlanmış bir ortam değişkeni unutulduğunda görülür.
Connector kaydı iki kez ekleniyor
WP AI Client sağlayıcı eklentisi zaten otomatik keşfediliyorsa manuel kayıt eklemeyin. Meta veriyi değiştirmek gerekiyorsa is_registered() → unregister() → register() desenini kullanın.
Özel kimlik doğrulama arayüzü görünmüyor
WordPress 7.0’da api_key connector’ları tam arayüz desteğine sahiptir. none veya özel yöntemler registry’de tutulabilse de gereken ön yüz bileşenini eklentinizin JavaScript tarafında kaydetmesi gerekebilir.
Anahtar veritabanında güvenli sanılıyor
Arayüzde yıldızlarla maskelenmesi şifreleme değildir. WordPress 7.0 ilk sürümünde veritabanı değerleri şifrelenmez. Anahtarın risk profili yüksekse ortam değişkeni kullanın ve sağlayıcı tarafındaki izinlerini daraltın.
Deneyimden çıkarılan uygulama notu
Geliştirme sırasında WordPress Connectors API hakkında gerçek bir yanlış varsayım kolayca kurulabilir: “Connector kaydı varsa servis çağrısı da hazırdır.” Resmi dev note’taki public fonksiyonlar incelendiğinde bunların yalnızca registry sorguladığı görülür. Servise ait HTTP istemcisi ayrıca gerekir. Aynı şekilde ConnectorInterface, wp_connector() veya yerleşik RateLimiter gibi isimler resmi WordPress 7.0 API’sinin parçası değildir. Kod tamamlama aracının ürettiği bu tür çağrılar, çalıştırıldığında “Call to undefined function” ya da “Class not found” hatasına dönüşür.
Bu yüzden entegrasyonu önce küçük bir eklentide sınayın. wp_get_connector() çıktısını doğrulayın, ardından sağlayıcı istemcisini ayrı test edin. Bu sıralama, registry sorunu ile uzak servis sorununu birbirinden ayırır.
Sıkça Sorulan Sorular
WordPress Connectors API yalnızca yapay zekâ için mi?
Registry farklı türleri kabul eder ve gelecekte kapsamın genişlemesi hedeflenir. Ancak WordPress 7.0’ın hazır yönetim deneyimi ve otomatik keşif akışı öncelikle AI sağlayıcılarına yöneliktir. Ödeme veya CRM entegrasyonu için istemci ve özel arayüz kodu yine gerekir.
API anahtarları WordPress veritabanında şifreleniyor mu?
Hayır. Yönetim ekranında maskelenirler fakat WordPress 7.0’ın ilk sürümünde veritabanında şifreli tutulmazlar. Uygunsa ortam değişkeni kullanmak ve sağlayıcı anahtarına dar yetki vermek daha güvenlidir.
Bir AI sağlayıcı eklentisini manuel kaydetmek gerekir mi?
WP AI Client’ın varsayılan registry’sine doğru biçimde kayıt yapan sağlayıcılar otomatik keşfedilir. Böyle bir sağlayıcı için ayrıca connector kaydı eklemek yerine gerekirse mevcut meta veriyi wp_connectors_init içinde değiştirin.
Connector bilgisi ne zaman sorgulanabilir?
Public sorgu fonksiyonları init sonrasında kullanılabilir. Kayıt ekleme ve değiştirme işlemleri ise wp_connectors_init aksiyonunda yapılmalıdır.
plugin.slug neden çalışmıyor?
Güncel WordPress 7.0 veri biçimi plugin.file alanını kullanır. Değer, ai-provider-for-anthropic/plugin.php gibi eklentinin ana dosyasına giden göreli yoldur. Eski plugin.slug alanı sessizce atılabilir.
Sonuç
WordPress Connectors API, harici servislerin kimlik ve bağlantı meta verisini WordPress düzeyinde standartlaştırır. En güçlü yanı; AI sağlayıcılarını keşfetmesi, anahtar kaynağını belirli bir öncelikle çözmesi ve bağlantıları Ayarlar → Connectors ekranında birleştirmesidir.
Başarılı entegrasyon için API’nin sınırını doğru çizin: connector kaydı bağlantı yapılandırmasıdır, servis istemcisi değildir. Kayıtları wp_connectors_init içinde yönetin, sorgulamada public fonksiyonları kullanın ve anahtarların veritabanında şifrelenmediğini hesaba katın. Ayrıca WordPress Connectors API kullanan bir eklentide plugin.file yolunu, kimlik biçimini ve anahtar önceliğini dağıtımdan önce otomatik testlere bağlayın.
Uygulama testinde üç ayrı sonuç kaydedilmelidir: registry kaydının bulunması, seçilen anahtar kaynağı ve sağlayıcı istemcisinin gerçek bağlantı yanıtı. Bu ayrım, yönetim ekranında görünen bir kartın uzaktaki servisin çalıştığını garanti etmediğini açıkça gösterir. Çoklu ortam kullanan ekiplerde aynı kontrolü geliştirme, test ve üretim için ayrı yürütmek; yanlış anahtarın gölgelenmesini ve üretim kimlik bilgilerinin test ortamına taşınmasını önler.
Ayrıntılar için resmi Connectors API dev note’unu ve WordPress 7.0 Field Guide’ı inceleyebilirsiniz.
WordPress 7.0 geliştirme başlıklarını izliyorsanız WordPress AI Client API rehberimize ve WordPress REST API içeriklerimize de göz atın. Kendi connector eklentinizde karşılaştığınız gerçek hata mesajını yorumlarda paylaşın; teşhis adımlarını birlikte değerlendirelim.
Dahili linkler:
