Veri depolama

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Azure DevOps uzantıları, kullanıcı tercihlerini ve karmaşık veri yapılarını doğrudan Microsoft tarafından sağlanan altyapıda depolayabilir ve bu sayede kullanıcınızın verilerinin de diğer kuruluş ve proje verileri gibi güvenli ve yedeklenmiş olmasını sağlar. Ayrıca, uzantı sağlayıcısı olarak basit veri depolama gereksinimlerinde üçüncü taraf veri depolama hizmetlerini ayarlamak, yönetmek veya ödemek zorunda olmadığınız anlamına gelir.

Veri depolama hizmetiyle etkileşim kurmak için iki yöntem vardır: REST API'leri aracılığıyla veya VSS SDK'sının bir parçası olan Microsoft tarafından sağlanan bir istemci hizmeti aracılığıyla. Uzantı geliştiricilerine sağlanan istemci hizmeti API'lerini kullanmalarını öneririz. Rest API'lerinin kullanımı kolay bir şekilde kapsüllenmesi sağlanır.

Desteklenen veri türleri

Hizmet, iki farklı veri türünü depolamanıza ve yönetmenize olanak sağlamak için tasarlanmıştır:

• Ayarları: basit anahtar-değer ayarları (kullanıcı tercihleri gibi)
• Belgeler: benzer karmaşık nesne koleksiyonları (belgeler)

Koleksiyon, belgeler için endekslenmiş bir kapsayıcıdır. Belge, bir koleksiyona ait olan bir JSON blobudur. Birkaç ayrılmış özellik adı dışında, bu belgelerin şemasını denetler ve yönetirsiniz.

Veri kapsamını belirleme

Ayarlar ve belge koleksiyonlarının kapsamı şu şekilde olabilir:

• Proje Koleksiyonu: uzantının yüklendiği proje koleksiyonunun tüm kullanıcıları tarafından paylaşılır
• Kullanıcı: Uzantının yüklendiği proje koleksiyonunun tek kullanıcısı

Ayarlar saklama

Ayarları yönetmek için iki ana yöntem getValue() ve setValue():

• getValue() bir dize anahtarı (kapsam gibi diğer seçeneklerle birlikte) kabul eder ve bir IPromise döndürür. Bu taahhüdün çözümlenen değeri, sağlanan anahtarla ilişkili değerdir.
• setValue() bir dize anahtarı, bir değer ve kapsam gibi diğer seçenekleri kabul eder ve bir IPromise döndürür. Bu promise'ın çözümlenen değeri, ayarın güncellenmiş değeridir.

Aşağıda, bir değerin nasıl ayarlanacağına yönelik bir örnek verilmişti:

        private async initializeState(): Promise<void> {
        await SDK.ready();
        const accessToken = await SDK.getAccessToken();
        const extDataService = await SDK.getService<IExtensionDataService>(CommonServiceIds.ExtensionDataService);
        this._dataManager = await extDataService.getExtensionDataManager(SDK.getExtensionContext().id, accessToken);

        this._dataManager.getValue<string>("test-id").then((data) => {
            this.setState({
                dataText: data,
                persistedText: data,
                ready: true
            });
        }, () => {
            this.setState({
                dataText: "",
                ready: true
            });
        });
    }

İşte bir ayar değerini nasıl alacağınızın bir örneği:

    // Get data service
    SDK.getService(SDK.getContributionId()).then(function(dataService) {
        // Get value in user scope
        dataService.getValue("userScopedKey", {scopeType: "User"}).then(function(value) {
            console.log("User scoped key value is " + value);
        });
    });

scopeType belirtilmezse, ayarlar proje koleksiyonu düzeyinde depolanır ve uzantıyı kullanarak bu proje koleksiyonundaki tüm kullanıcılar tarafından erişilebilir. Aşağıda, proje koleksiyonu düzeyinde bir ayar değerinin nasıl ayarlanacağına ilişkin bir örnek verilmişti:

    // Get data service
    SDK.getService(SDK.getContributionId()).then(function(dataService) {
        // Set value (default is project collection scope)
        dataService.setValue("someKey", "abcd-efgh").then(function(value) {
            console.log("Key value is " + value);
        });
    });

Veri (belge koleksiyonları) depolama

Anahtar-değer çiftlerinin ötesinde daha karmaşık verileri işlemek için, uzantınızın verileri üzerinde CRUD işlemlerini yürütmek için belge kavramını kullanabilirsiniz. Belge, iki özel özellik ile geliştirilmiş bir JSON blobudur: Id ve __etag. Bir uzantının veri modeli için önemliyse, kimlikler kullanıcı tanımlı olabilir veya belirtilmemiş bırakılırsa sistem bunları oluşturur. Bu kimlikler belirli bir koleksiyon içinde benzersiz olmalıdır. Koleksiyon, bir uzantının belirli bir kapsamına ve örneğine başvurduğundan, aynı belge kimliğinin farklı koleksiyonlar arasında yeniden kullanılabileceği anlamına gelir.

Aşağıdaki belge işlemleri kullanılabilir:

• Belge alma
• Belge oluşturma
• Belge ayarlama (oluşturma veya güncelleştirme)
• Bir belgeyi güncelleştirme
• Belgeyi silme

Bir koleksiyonda gerçekleştirilebilecek tek bir işlem de vardır: Tüm belgeleri alma

ID ile belge al

Tanımlayıcısını kullanarak bir koleksiyondan belge almak, aşağıdaki örnekte olduğu gibi basittir:

    // Acquire data service
    SDK.getService(SDK.getContributionId()).then(function(dataService) {
        // Retrieve document by id
        dataService.getDocument("MyCollection", "MyDocumentId").then(function(doc) {
            // Assuming document has a property named foo
            console.log("Doc foo: " + doc.foo);
        });
    });

Bu işlem, "MyCollection" koleksiyonundan "MyDocumentId" kimliğine sahip bir belgeyi getirmeye çalışır. Sağlanan bir kapsamın olmaması halinde hizmet varsayılan olarak bu uzantının tüm örneği kapsamındaki koleksiyonu kullanır. Eğer bu koleksiyon ya da belirtilen ID'ye sahip bir belge yoksa, uzantının işlemesi gereken bir 404 hatası döndürülür. Döndürülen belge, veri depolama hizmeti tarafından kullanılan özel kimlik ve __etag özelliklerin yanı sıra tüm özelliklerini içeren bir JSON nesnesidir.

    // Get data service
    SDK.getService(SDK.getContributionId()).then(function(dataService) {
        // Get document by id
        dataService.getDocument("MyCollection", "MyDocumentId").then(function(doc) {
            // Assuming document has a property named foo
            console.log("Doc foo: " + doc.foo);
        });
    });

Bu çağrı, "MyCollection" koleksiyonundan "MyDocumentId" kimliğine sahip bir belge almayı dener. Kapsam sağlanmadığından, hizmetin kullandığı koleksiyon, bu uzantının tüm örneğinin varsayılan kapsamına alınır. Uzantının işlemesi gereken bir 404 hatası döndürülür, eğer bu koleksiyon yoksa veya bu kimlikle bir belge mevcut değilse. Döndürülen belge, veri depolama hizmeti tarafından kullanılan özel kimlik ve __etag özelliklerine ek olarak tüm kendi özelliklerini içeren bir JSON nesnesidir.

Belge oluşturma

Yeni bir belge oluşturmak için aşağıdaki örneğe benzer bir çağrı yapın:

    // Get data service
    SDK.getService(SDK.getContributionId()).then(function(dataService) {
        // Prepare document first
        var newDoc = {
            fullScreen: false,
            screenWidth: 500
        };

        dataService.createDocument("MyCollection", newDoc).then(function(doc) {
            // Even if no ID was passed to createDocument, one gets generated
            console.log("Doc id: " + doc.id);
        });
    });

Adı ve kapsamı sağlanan koleksiyon henüz mevcut değilse, belge oluşturulmadan önce dinamik olarak oluşturulur.

Sağlanan belge bir id özelliği içeriyorsa, bu değer belgenin benzersiz kimliği olarak kullanılır. Sağlananın id 50 karakterle sınırlı olması gerektiğini unutmayın. Bu alan mevcut değilse, hizmet tarafından bir GUID oluşturulur ve vaat yerine getirildiğinde döndürülen belgeye eklenir.

Koleksiyondaki başka bir belge, belirtilen kimlikle aynı kimliğe sahipse, işlem başarısız olur. İstenen davranış, kimlik yoksa yeni bir belge oluşturmak, ancak kimlik varsa mevcut belgeyi değiştirmek ise, o zaman setDocument() yöntemi kullanılmalıdır.

Belge ayarlama (güncelleştirme veya oluşturma)

setDocument() işlevi bir "upsert" işlemi yürütür; kimliği mevcutsa mevcut bir belgeyi değiştirir ve koleksiyondaki bir belgeyle eşleşir. Kimlik yoksa veya koleksiyondaki herhangi bir belgeye karşılık gelmiyorsa koleksiyona yeni bir belge eklenir.

    // Get data service
    SDK.getService(SDK.getContributionId()).then(function(dataService) {
        // Prepare document first
        var myDoc = {
            id: 1,
            fullScreen: false,
            screenWidth: 500
        };

        dataService.setDocument("MyCollection", myDoc).then(function(doc) {
            console.log("Doc id: " + doc.id);
        });
    });

Bir belgeyi güncelleştirme

updateDocument işlevi, değiştirilen belgenin koleksiyonda zaten bulunması gerekir. Kimlik sağlanmazsa veya sağlanan kimlik koleksiyondaki herhangi bir belgeye karşılık gelmiyorsa bir özel durum oluşturulur.

Güncelleştirmenin nasıl kullanıldığına yönelik bir örnek aşağıda verilmiştir:

    // Get data service
    SDK.getService(SDK.getContributionId()).then(function(dataService) {
        var collection = "MyCollection";
        var docId = "1234-4567-8910";
        // Get document first
        dataService.getDocument(collection, docId, { scopeType: "User" }).then(function(doc) {
            // Update the document
            doc.name = "John Doe";
            dataService.updateDocument(collection, doc, { scopeType: "User" }).then(function(d) {
                // Check the new version
                console.log("Doc version: " + d.__etag);
            });
        });
    });

Belgeyi silme

Bu işlev, sağlanan kimlikle belgeyi sağlanan koleksiyondan siler. Koleksiyon yoksa veya belge yoksa 404 döndürülür.

Aşağıda örnek bir kullanım verilmiştir:

    // Get data service
    SDK.getService(SDK.getContributionId()).then(function(dataService) {
        var docId = "1234-4567-8910";
        // Delete document
        dataService.deleteDocument("MyCollection", docId).then(function() {
            console.log("Doc deleted");
        });
    });

Koleksiyondaki tüm belgeleri alma

Aşağıdaki örnek, veri hizmetini kullanarak "MyCollection" koleksiyonundaki tüm belgeleri alır ve ardından belge adedini konsolda yazar.

    // Get data service
    SDK.getService(SDK.getContributionId()).then(function(dataService) {
        // Get all document under the collection
        dataService.getDocuments("MyCollection").then(function(docs) {
            console.log("There are " + docs.length + " in the collection.");
        });
    });

Bu çağrı, 100.000 belge sınırıyla tanımlı bir koleksiyondaki tüm belgeleri alır. Koleksiyon yok ise 404 hatası döndürür.

Gelişmiş

Ayarlar nasıl depolanır?

Bu çağrı, setDocument istemci yöntemini kapsülleyerek onu birden çok veri parçasıyla besler. Daha önce belirtildiği gibi, ayarlar dahili olarak belge olarak kaydedilir. Bu nedenle, temel bir belge dinamik olarak oluşturulur ve burada belgenin kimliği setValue() yönteminde verilen anahtardır. Belgenin iki özelliği daha var. value özelliği yöntemine geçirilen değeri tutar ve revision özelliği -1olarak ayarlanır. revision özelliği "Belgelerle Çalışma" bölümünde daha ayrıntılı olarak anlatılsa da, ayarlar bağlamında revision belgedeki -1 olarak ayarlamak, bu ayarlar belgesinin sürümüyle ilgilenmediğimize işaret eder.

Ayarlar belge olarak depolandığından, belgenin depolandığı yeri belirten bir koleksiyon adı sağlamamız gerekir. İşleri basit tutmak için, setValue()/getValue() yöntemleriyle çalışırken koleksiyon adı her zaman $settingsözel addır. Önceki çağrı aşağıdaki uç noktada bir PUT İsteği oluşturur:

GET _apis/ExtensionManagement/InstalledExtensions/{publisherName}/{extensionName}/Data/Scopes/User/Me/Collections/%24settings/Documents

İstek yükü aşağıdaki örneğe benzer:

{
                "id": "myKey",
                "__etag": -1,
                "value": "myValue"
}

REST API'leri

Bu kod parçacığının değer ayarlandıktan sonra yürütüldüğnü varsayarsak, "Değer myValue değeridir" metnini içeren bir uyarı iletisi görmeniz gerekir. getValue yöntemi, rest API'lerinin etrafındaki bir sarmalayıcıdır ve aşağıdaki uç noktaya bir GET isteği döndürür:

GET _apis/ExtensionManagement/InstalledExtensions/{publisherName}/{extensionName}/Data/Scopes/User/Me/Collections/%24settings/Documents/myKey

etag'ler

__etag alanı, belge eşzamanlılık yönetimi için Veri Depolama Hizmeti tarafından kullanılır. Bir güncelleştirme kaydedilmeden önce hizmet, şu anda depolanan belgenin __etag güncelleştirilmiş belgenin __etag eşleşeceğini doğrular. Eşleşmeleri durumunda, __etag artırılır ve güncellenen belge çağırana geri gönderilir. Eşleşmiyorsa, güncelleştirilecek belgenin güncel olmadığını ve bir özel durum oluştuğuna işaret eder. Eklenti geliştiricisi, belgenin en son __etag sürümünü alıp değişiklikleri birleştirerek ve güncellemeyi tekrar deneyerek veya kullanıcıyı bilgilendirerek bu özel durumu düzgün bir şekilde işlemekle sorumludur.

Bazı belge türleri için, sağlanan eşzamanlılık düzeyi gerekli olmayabilir ve son kazananlar modeli daha uygun olabilir. Bu tür durumlarda belgeyi düzenlerken, bu işlevselliği belirtmek için __etag değeri olarak -1 girişini yapın. Daha önce bahsedilen ayarlar hizmeti, ayarları ve tercihleri depolamak için bu modeli kullanır.