API:Uzantılar
Bu sayfa MediaWiki Eylem API'si belgelerinin bir parçasıdır. |
Bu belge, MediaWiki 1.30 ve sonraki sürümlerle kullanım için bir uzantıda bir API modülü oluşturmayı kapsar.
Modül oluşturma ve kaydetme
Tüm API modülleri ApiBase alt sınıflarıdır, ancak bazı modül türleri türetilmiş bir temel sınıf kullanır. Kayıt yöntemi modül tipine de bağlıdır.
- eylem modülleri
- Ana
action
parametresi için değer sağlayan modüller ApiBase alt sınıfını içermelidir.APIModules
anahtarı kullanılarakextension.json
olarak kaydedilmelidirler. - biçim modülleri
- Ana
format
parametresi için değer sağlayan modüllerin ApiFormatBase alt sınıfı olmalıdır.APIFormatModules
anahtarı kullanılarakextension.json
biçiminde kaydedilmelidirler. Bir uzantının bir biçim modülü eklemesi çok nadirdir. - sorgu modülleri
prop
,list
veyameta
parametreleri içinaction=query
ile bir değer sağlayan modüller ApiQueryBase (bir jeneratör olarak kullanılamazsa) veya ApiQueryGeneratorBase (bir jeneratör olarak kullanılabilirse) alt sınıfına sahip olmalıdır. $APPropModules,APIListModules
veyaAPIMetaModules
anahtarı kullanılarakextension.json
biçiminde kaydedilmelidir.
Her durumda, kayıt anahtarının değeri, anahtar olarak modül adına (yani parametrenin değeri) ve değer olarak sınıf adına sahip bir nesnedir. Modüller ayrıca $hook1 (eylem ve format modülleri için) ve $hook2 (sorgu alt modülleri için) kancaları kullanılarak koşullu olarak kaydedilebilir. Modules may also be registered conditionally using the ApiMain::moduleManager (for action and format modules) and ApiQuery::moduleManager (for query submodules) hooks.
Uygulama
Önek
API modülünüzün yapıcısında parent::__construct()
öğesini çağırdığınızda modülünüzün parametreleri için isteğe bağlı bir önek belirleyebilirsiniz.
(Bir modülün oluşturulan belgelerinde, varsa bu önek, modül başlığında parantez içinde görünür.)
Modülünüz bir sorgu alt modülü ise, bir önek gereklidir, çünkü istemci tek bir istekte her biri kendi parametrelerine sahip birden fazla alt modül çağırabilir. Eylem ve biçim modülleri için önek isteğe bağlıdır.
For action and format modules, the prefix is optional.
Parametreler
Çoğu modül parametre gerektirir. Bunlar $getAllowedParams uygulanarak tanımlanır. Dönüş değeri, anahtarların (önceden düzeltilmemiş) parametre adları ve değerlerinin parametre için skaler varsayılan değer olduğu veya $ApiBase tarafından tanımlanan $param sabitlerini kullanarak parametrenin özelliklerini tanımlayan bir dizi olduğu ilişkisel bir dizidir.
These are defined by implementing getAllowedParams().
The return value is an associative array where keys are the (unprefixed) parameter names and values are either the scalar default value for the parameter or an array defining the properties of the parameter using the PARAM_*
constants defined by ApiBase.
Örnek, sözdizimini ve daha yaygın olan PARAM_*
sabitlerini göstermektedir.
protected function getAllowedParams() {
return [
// Varsayılan değeri olan isteğe bağlı bir parametre
'simple' => 'value',
// Gerekli bir parametre
'required' => [
ApiBase::PARAM_TYPE => 'string',
ApiBase::PARAM_REQUIRED => true,
],
// Bir listeden birden fazla değeri kabul eden bir parametre
'variable' => [
// Varsayılan değer kümesi
ApiBase::PARAM_DFLT => 'foo|bar|baz',
// Tüm olası değerler
ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
// Birden çok değerin kabul edildiğini belirtin
ApiBase::PARAM_ISMULTI => true,
// Standart "değer başına" belge mesajlarını kullanın
ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
],
// Standart bir "limit" parametresi. Genellikle bu standarttan farklı olmamak en iyisidir.
'limit' => [
ApiBase::PARAM_DFLT => 10,
ApiBase::PARAM_TYPE => 'limit',
ApiBase::PARAM_MIN => 1,
ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
],
];
}
Parametreler MediaWiki'nin uluslararasılaştırma mekanizması kullanılarak belgelenmiştir. Ayrıntılar için #Belgeleme bölümüne bakın.
Yürütme ve çıkış
Aslında modülü uygulayan kod execute() yöntemine gider. Bu kod, giriş parametrelerini almak için genellikle $this→extractRequestParams() ve herhangi bir çıktı eklemek için ApiResult nesnesini almak için $this→getResult() kullanır.
Sorgu destekli alt modüller, üzerinde çalışılacak sayfa grubuna erişmek için $this→getPageSet() kullanmalıdır.
Oluşturucu olarak kullanılabilecek sorgu alt modüllerinin, oluşturulan sayfalarla doldurulması gereken ApiPageSet bir geçmiş olan executeGenerator() uygulaması gerekecektir.
Bu durumda, ApiResult
genellikle kullanılmamalıdır.
Önbelleğe almak
Varsayılan olarak API yanıtları önbelleklenemez ('Cache-Control: private') olarak işaretlenir!
Eylem modülleri için, $this→getMain()→setCacheMode() çağırarak önbelleğe almaya izin verebilirsiniz.
Bu, istemcilerin önbelleğe almayı gerçekten etkinleştirmek için maxage
veya smaxage
parametrelerini geçmesini gerektirir.
Önbelleği $this→getMain()→setCacheMaxAge() çağırarak da zorlayabilirsiniz.
Sorgu modülleri için bu yöntemleri çağırmayın. Bunun yerine getCacheMode() uygulayarak önbelleğe almaya izin verebilirsiniz.
Her iki durumda da, özel verilerin gösterilmediğinden emin olun.
Anahtar kullanımı
Eylem modülünüz vikiyi herhangi bir şekilde değiştirirse, bir tür anahtar gerektirir.
Bunun otomatik olarak ele alınması için, modülünüzün gerektirdiği anahtarı (muhtemelen 'csrf'
düzenleme anahtarı) döndürerek needsToken()
yöntemini uygulayın.
API temel kodu, istemcilerin API isteklerinde sağladıkları anahtarı token
parametresinde otomatik olarak doğrular.
Çekirdeğin parçası olan bir anahtar kullanmak istemiyorsanız, ancak kendi izin denetimlerinizle birlikte özel bir anahtar kullanmak istiyorsanız, anahtarınızı kaydetmek için ApiQueryTokensRegisterTypes kancası kullanın.
Master veritabanı erişimi
Modülünüz ana veritabanına erişirse, true
döndürmek için isWriteMode()
yöntemini uygulamalıdır.
Dönüş hataları
ApiBase, çeşitli kontroller yapmak için çeşitli yöntemler içerir, örneğin,
- Bir parametre kümesinden tam olarak sağlandığını iddia etmeniz gerekiyorsa, $this→requireOnlyOneParameter() kullanın.
- Bir parametre kümesinden en fazla birinin sağlandığını iddia etmeniz gerekiyorsa, $this→requireMaxOneParameter() kullanın.
- Bir parametre kümesinden en az birinin sağlandığını iddia etmeniz gerekiyorsa, $this→requireAtLeastOneParameter() kullanın.
- Kullanıcının belirli hakları olduğunu iddia etmeniz gerekiyorsa, $this→checkUserRightsAny() kullanın.
- Kullanıcının belirli bir sayfada işlem yapabileceğini iddia etmeniz gerekiyorsa, $this→checkTitleUserPermissions() kullanın.
- Kullanıcı engellenirse (ve modülünüz için önemliyse),
Block
nesnesini $this→dieBlocked() öğesine iletin.
Ancak genellikle kendi hatanızı yükseltmeniz gereken durumlarda karşılaşırsınız.
Bunu yapmanın genel yolu $this→dieWithError() çağırmaktır, ancak hata bilgisiyle StatusValue
varsa bunun yerine $this→dieStatus() geçebilirsiniz.
Bir hata yerine uyarı vermeniz gerekiyorsa, kullanımdan kaldırma uyarısı ise $this→addWarning() veya $this→addDeprecation() kullanın.
Belgelendirme
API, MediaWiki'nin uluslararasılaştırma mekanizması kullanılarak belgelenmiştir. Gerekli mesajlar genellikle modülün "path" temel alan varsayılan isimlere sahiptir. Eylem ve biçim modülleri için yol, kayıt sırasında kullanılan modülün adıyla aynıdır. Sorgu alt modülleri için, "query+" önekine sahip addır. Needed messages generally have default names based on the module's "path". For action and format modules, the path is the same as the module's name used during registration. For query submodules, it's the name prefixed with query+.
Her modülün tek satırlık açıklaması olması gereken apihelp-$path-summary
bir iletiye ihtiyacı olacaktır.
Ek yardım metni gerekirse, apihelp-$path-extended-description
ile oluşturulabilir.
Her parametrenin apihelp-$path-param-$name
mesajına ihtiyacı vardır ve PARAM_HELP_MSG_PER_VALUE
kullanan parametrelerin de her değer için apihelp-$path-paramvalue-$name-$value
ihtiyacı vardır.
API belgeleriyle ilgili daha fazla ayrıntı API:Yerelleştirme altında edinilebilir.
Uzantılar, Wikimedia'da ek API belgeleri de tutabilir.
Bu, uzantının ana sayfasında veya daha fazla yer gerekirse, Extension:<ExtensionName>/API
veya alt sayfalarında (ör. CentralAuth , MassMessage veya StructuredDiscussions ) yer almalıdır.
API ad alanı, MediaWiki çekirdeğinin API'si için ayrılmıştır.
Temel modülleri genişletme
MediaWiki 1.14'ten bu yana, çekirdek modüllerin işlevselliğini aşağıdaki kancaları kullanarak genişletmek mümkündür:
- APIGetAllowedParams - modülün parametre listesini eklemek veya değiştirmek için
- APIGetParamDescriptionMessages - modülün parametre açıklamalarını eklemek veya değiştirmek için
- APIAfterExecute - modül yürütüldükten sonra (ancak sonuç çıkmadan önce)
prop=
,list=
vemeta=
modülleri için APIQueryAfterExecute kullanın- Modül jeneratör modunda çalıştırılırsa, bunun yerine APIQueryGeneratorAfterExecute çağıracaktır
API işlevine sahip uzantıların listesi
API'ya eklenen veya API'yi genişleten uzantı örnekleri için Category:API uzantıları sayfasına bakın.
Uzantınızı test etme
- api.php ziyaret edin ve modül veya sorgu alt modülü için oluşturulan yardıma gidin. Uzantınızın yardım bilgileri doğru olmalıdır.
getExamplesMessages()
olarak verdiğiniz örnek URL'ler "Örnekler" altında görünmelidir, tıklamayı deneyin.- Sorgu dizesindeki URL parametrelerini atlayın ve yönetin, uzantınızın yanıtını kontrol edin.
- Special:ApiSandbox syfasını ziyaret edin ve API'nizi etkileşimli olarak keşfedin.
- Uzantınızla ilgili ek bilgileri görmek için $api sayfasını ziyaret edin.