Toplu İndirme ve Karşıya Yükleme
Toplu hizmet ile kampanya ayarlarını arka planda zaman uyumsuz olarak indirebilir ve karşıya yükleyebilirsiniz. Özellikle bir hesaptaki birden çok reklam grubuna veya kampanyaya reklam ve anahtar sözcük eklemeniz veya güncelleştirmeniz gerekiyorsa, büyük ölçekli verileri yönetmek için Toplu hizmet önerilir. Bazı varlıklar için teklif önerilerini ve kalite puanı verilerini de indirebilirsiniz. Aynı dosyadaki diğer kayıtlar hata içerse de içermese de her kayıt başarıyla karşıya yüklenebilir. Hangi varlıkların, teklif önerilerinin ve kalite puanı verilerinin kullanılabilir olduğuyla ilgili ayrıntılar da dahil olmak üzere dosya indirme ve karşıya yükleme için kullanılan şema hakkında bilgi için bkz. Toplu Dosya Şeması.
Önemli
Yeni kayıt türleri (satırlar) ve alanlar (sütunlar) her zaman eklenebilir ve toplu indirme veya toplu karşıya yükleme sonuçları dosyasındaki kayıt veya alan sırasına bağlı olmamalıdır. Benzer şekilde, başvuru belgelerinde aksi belirtilmedikçe, her alanda döndürülen sabit bir değer kümesine bağımlı olmamalıdır.
.NET dili, Java veya Python kullanıyorsanız Bing Ads API İstemci Kitaplıklarını kullanmanız gerekir. .NET, Java ve Python SDK'ları aşağıda açıklanan düşük düzey ayrıntıları soyutlar. Örneğin, dosya indirmek için DownloadCampaignsByAccountIds ve GetBulkDownloadStatus çağrıları yerine BulkServiceManager sınıfıyla tek bir yöntem kullanabilirsiniz. SDK'larla toplu indirme ve yükleme kullanma hakkında daha fazla bilgi için bkz. Toplu Service Manager.
Toplu İndirme
Bir hesabın kampanya verilerini indirmek için DownloadCampaignsByAccountIds işlemini çağırın. Belirli kampanyaların verilerini indirmek için DownloadCampaignsByCampaignIds işlemini çağırın.
Toplu Dosya İndirme
Kampanyanın tüm verilerini veya yalnızca kampanya verilerini son indirdiğinizden bu yana değişen verileri isteyebilirsiniz. her iki indirme işlemi için de, istek ayarlarına ve indirme iş akışına genel bir bakış aşağıdadır.
Önemli
İndirme isteği işlemi ( DownloadCampaignsByAccountIds veya DownloadCampaignsByCampaignIds) ve GetBulkDownloadStatus yoklama işlemi için aynı kullanıcı kimlik bilgilerini kullanmanız gerekir.
İsteğin DataScope öğesini ayarlayın ve varlık verilerine ek olarak teklif önerilerinin mi yoksa kalite puanı verilerinin mi ekleneceğini belirtin. Olası değerlerin listesi için bkz. DataScope değer kümesi.
İndirme dosyasının biçimi için Csv veya Tsv'yi seçmek için isteğin DownloadFileType öğesini ayarlayın.
Not
İndirilen Csv veya Tsv dosyası, belirttiğiniz CompressionType'a bağlı olarak ZIP veya GZIP sıkıştırılmış olur. CompressionType belirtmediyseniz ZIP varsayılan değerdir.
İsteğin Varlıklar öğesini kampanyanızı, reklam grubunuzu, reklamınızı ve anahtar sözcük varlıklarınızı içerecek şekilde ayarlayın. İsteğe bağlı olarak indirmeye negatif anahtar sözcükler ve hedefler gibi ek varlıklar ekleyebilirsiniz. İsteyebileceğiniz varlıkların listesi için bkz. DownloadEntity değer kümesi.
İsteğin LastSyncTimeInUTC öğesini önceki indirmenin zaman damgasına ayarlayarak yalnızca son indirmeden bu yana güncelleştirilmiş veya silinmiş olan varlıkları isteyin.
Not
Belirtilen varlıklar için ilk kez indirme isteğinde bulunuyorsanız, tüm kullanılabilir varlıkları indirmek için isteğin LastSyncTimeInUTC öğesini NULL olarak ayarlayın.
İndirme isteğini DownloadCampaignsByAccountIds veya DownloadCampaignsByCampaignIds işlemiyle gönderin.
İndirme isteği , GetBulkDownloadStatus işlemine geçirdiğiniz bir tanımlayıcı döndürür. İndirme tamamlanana veya başarısız olana kadar GetBulkDownloadStatus işlemini döngü içinde çağırırsınız. İndirme işleminin tamamlanması için gereken süre, istediğiniz kampanya sayısı ve zaten kuyrukta olan istek sayısı gibi bir dizi değişkene bağlıdır. Bu değişkenler nedeniyle, kullandığınız yoklama aralığı farklılık gösterebilir. İndirme isteğini gönderdiğiniz zamandan itibaren dosyayı indirmek için iki gününüz vardır. Dosyayı bu süre içinde başarıyla indirmediyseniz, indirme sitesinden kaldırılır ve indirme işlemlerinden birini yeniden çağırmanız gerekir.
GetBulkDownloadStatus işlemi başarıyla tamamlandığında, indirme dosyasının URL'sini döndürür. İndirme dosyasını yerel olarak kopyalamak için URL'yi kullanın. URL, GetBulkDownloadStatus işleminin Bir Başarı durum kodu döndürdüğü zamandan sonra beş dakika içinde kullanılmalıdır. İndirme işlemini bu süre içinde başlatmazsanız, yeni bir URL almak için GetBulkDownloadStatus'ı yeniden çağırmanız gerekir.
İndirme dosyası zip biçiminde sıkıştırıldığından, verilere erişmek için dosyanın sıkıştırmasını açmanız gerekir. İndirme dosyası için kullanılan şema hakkında bilgi için bkz. Toplu Dosya Şeması.
En İyi Yöntemleri İndirme
Kendiniz ve tüm Microsoft Advertising müşterileri için adil kullanım sağlamak için lütfen en iyi yöntemlere uyun.
Önemli
Tam eşzamanlı indirme ve karşıya yükleme sınırları değiştirilebilir ancak gönderdiğiniz bekleyen isteklerin sayısı sınırlıdır. 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod hatasını gözlemlerseniz, gönderdiğiniz isteklerin sıklığına ve boyutuna bağlı olarak 15 dakikaya kadar bekledikten sonra isteğinizi yeniden gönderebilirsiniz. Daha fazla bilgi için bkz . Toplu API Azaltma.
Yalnızca ihtiyacınız olan toplu indirme varlıklarını isteyin. Yeni kayıt türleri (satırlar) ve alanlar (sütunlar) her zaman eklenebilir ve toplu indirme veya toplu karşıya yükleme sonuçları dosyasındaki kayıt veya alan sırasına bağlı olmamalıdır.
Tam indirme işlemini yalnızca bir kez gerçekleştirin. Bundan sonra delta indirmeleri gerçekleştirin. LastSyncTimeInUTC değerini son indirmenin zaman damgasına ayarlayın. İndirme dosyası, Hesap kaydının SyncTime sütununda indirmenin zaman damgasını içerir. Her seferinde tam indirme gerçekleştirmenin bir avantajı yoktur ve sizinki de dahil olmak üzere herkesin performansını düşürür.
makul aralıklarla indirmeleri yoklama. Verilerinizi herkesten daha iyi biliyorsunuz. Bir milyondan az anahtar sözcük içeren bir hesap indirirseniz 15-20 saniyelik aralıklarla yoklamayı göz önünde bulundurun. Hesap yaklaşık bir milyon anahtar sözcük içeriyorsa, beş dakika bekledikten sonra bir dakikalık aralıklarla yoklamayı göz önünde bulundurun. Yaklaşık dört milyon anahtar sözcüğü olan hesaplar için 10 dakika bekledikten sonra bir dakikalık aralıklarla yoklamayı göz önünde bulundurun.
Hesap dört milyondan fazla anahtar sözcük içeriyorsa DownloadCampaignsByCampaignIds işlemini çağırın. DownloadCampaignsByAccountIds işlemini dört milyondan fazla anahtar sözcük içeren bir hesapla çağırma başarısız olur.
DownloadCampaignsByCampaignIds isteğinize daha az kampanya eklemek isteyebilirsiniz. DownloadCampaignsByCampaignIds işlemini sekiz milyondan fazla anahtar sözcük içeren bir hesapla çağırma başarısız olur. Arama başına daha az kampanya belirten istekler genellikle izin verilen maksimum numarayı belirten çağrılardan daha erken tamamlanır.
Toplu Karşıya Yükleme
TOPLU yükleme dosyanızı HTTP POST ile toplu hizmet tarafından sağlanan bir Url'ye gönderebilirsiniz.
Not
Üretimde karşıya yükleme için dosya boyutu sınırı 100 MB ve en fazla 4 milyon satırdır. Korumalı Alan için sınır 20.000 satırdır.
Karşıya yükleme dosyası için kullanmanız gereken şema hakkında bilgi için bkz. Toplu Dosya Şeması.
Toplu Dosyayı Karşıya Yükleme
İstek ayarlarına ve karşıya yükleme iş akışına genel bakış aşağıdadır.
Önemli
GetBulkUploadUrl, HTTP POST ve GetBulkUploadStatus iş akışı boyunca aynı kullanıcı kimlik bilgilerini kullanmanız gerekir.
GetBulkUploadUrl isteğinin AccountId öğesini karşıya yüklenecek verilere karşılık gelen hesap tanımlayıcısına ayarlayın.
GetBulkUploadUrl isteğinin ResponseMode öğesini, hizmetin hata döndüreceğini ve karşılık gelen verileri mi yoksa yalnızca sonuç dosyasındaki hataları mı döndüreceğini belirtmek için ayarlayın. Daha fazla bilgi için bkz . ResponseMode.
Toplu karşıya yükleme dosyanızı HTTP POST ile göndermek için GetBulkUploadUrl yanıtıyla döndürülen UploadUrl dosyasını kullanın. İçerik türü çok parçalı/form-verisi olmalıdır. UTF-8 dosyaları bayt sipariş işaretini (BOM) içermelidir. ZIP ile sıkıştırılmış karşıya yükleme csv veya Tsv olarak biçimlendirilmiş bir dosya içermelidir. ZIP dosyasının, merkezi dizin kaydının sonu da dahil olmak üzere düzgün yapılandırılmış olması gerekir.
Not
HTTP standart Yetkilendirme üst bilgisi kullanılmaz. Kimlik doğrulaması yapmak için DeveloperToken, CustomerId ve CustomerAccountId üst bilgileri de dahil olmak üzere HTTP istemcinizin Microsoft Advertising özel üst bilgi öğelerini eklemeniz ve ayarlamanız gerekir. AuthenticationToken üst bilgisi öğesi aracılığıyla da kullanıcı kimlik bilgilerini ayarlamanız gerekir. Daha fazla bilgi için bkz. OAuth ile kimlik doğrulaması ve API Kimlik Bilgilerini Kullanma Yeri.
GetBulkUploadUrl, HTTP POST ve GetBulkUploadStatus iş akışı boyunca aynı kullanıcı kimlik bilgilerini kullanmanız gerekir.
İşte bir örnek.
POST <UploadUrl> HTTP/1.1 AuthenticationToken: <AuthenticationToken> DeveloperToken: <DeveloperToken> CustomerId: <CustomerId> AccountId: <AccountId> Content-Type: multipart/form-data;HTTP yanıt durumu kodunu denetleyin. HTTP yanıt durumu kodu 200 ise, dosya Microsoft Advertising tarafından başarıyla alınmıştı. HTTP yanıt durum kodu 401 ise kimlik doğrulaması başarısız oldu; örneğin AuthenticationToken veya DeveloperToken geçersizdi. HTTP yanıt durum kodu 400 ise, örneğin 3220 - 3227 aralığında Bing Ads API İşlem Hata Kodları için yanıt akışını da denetlemeniz gerekir.
Burada, URL'nin toplu dosyayı karşıya yüklemek için zaten kullanıldığını belirten örnek bir hata yanıt iletisi verilmiştir.
HTTP/1.1 400 Bad Request Cache-Control: private Content-Type: application/json; charset=utf-8 Server: Microsoft-IIS/8.0 X-AspNetMvc-Version: 3.0 X-AspNet-Version: 4.0.30319 X-Powered-By: ASP.NET Date: Tue, 12 Jan 2016 17:07:23 GMT Content-Length: 224 {"TrackingId":"16bd93cc-22fb-4d3c-94be-25adefd06fae","RequestId":"26c3fbf6-3e24-4569-ada3-d4e8b3d0aecc","Code":3224,"ErrorCode":"BulkServiceUrlAlreadyUsedForUpload","Message":"The URL has already been used for file upload."}GetBulkUploadUrl yanıtı, GetBulkUploadStatus işlemine geçirdiğiniz bir RequestId de içerir. Karşıya yükleme beklemede olsa da, karşıya yükleme tamamlanana veya başarısız olana kadar döngüde GetBulkUploadStatus işlemini çağırabilirsiniz. Karşıya yükleme isteğini gönderdiğiniz zamandan itibaren karşıya yükleme sonuçları dosyasını indirmek için on beş dakikanız vardır. Bu süre içinde dosyayı başarıyla indirmediyseniz, indirme sitesinden kaldırılır ve alınamayabilir. Bu fırsat penceresini kaçırırsanız, en son varlık verilerini almak için indirme işlemlerinden birini çağırabilirsiniz.
GetBulkUploadStatus işlemi başarıyla tamamlandığında, karşıya yükleme sonuçları dosyasının URL'sini döndürür. Sonuç dosyasını yerel olarak kopyalamak için URL'yi kullanın. URL, GetBulkUploadStatus işleminin Tamamlandı durum yanıt dizesini döndürdüğü zamandan sonra on beş dakika içinde kullanılmalıdır. İndirme işlemini bu süre içinde başlatmazsanız, yeni bir URL almak için GetBulkUploadStatus'ı yeniden çağırmanız gerekir.
Not
Karşıya yükleme sonuç dosyasının biçimi Csv veya Tsv olur ve karşıya yükleme için gönderdiğiniz dosyanın biçimiyle eşleşecektir.
Karşıya Yükleme En İyi Yöntemleri
Kendiniz ve tüm Microsoft Advertising müşterileri için adil kullanım sağlamak için lütfen en iyi yöntemlere uyun.
Önemli
Tam eşzamanlı indirme ve karşıya yükleme sınırları değiştirilebilir ancak gönderdiğiniz bekleyen isteklerin sayısı sınırlıdır. 4204 BulkServiceNoMoreCallsPermittedForTheTimePeriod hatasını gözlemlerseniz, gönderdiğiniz isteklerin sıklığına ve boyutuna bağlı olarak 15 dakikaya kadar bekledikten sonra isteğinizi yeniden gönderebilirsiniz. Daha fazla bilgi için bkz . Toplu API Azaltma.
Büyük dosyalar karşıya yükleme performansını düşürebilir. İsteğe bağlıdır ve karşıya yükleme için dosyanın sıkıştırılması önerilir. Sıkıştırılmışsa ilgili uzantıyla ZIP olarak biçimlendirilmelidir. Üretimde karşıya yükleme için dosya boyutu sınırı 100 MB ve en fazla 4 milyon satırdır. Korumalı Alan için sınır 20.000 satırdır. Müşteri başına eşzamanlı yüklemeleri 5 veya 6'nın altında sınırlayabilirseniz, dosya boyutu sınırına yaklaşmak yerine dosyayı bölmeyi göz önünde bulundurun.
Dosyaları paralel olarak karşıya yüklemek için eş zamanlı karşıya yüklemeleri müşteri başına 5 veya 6 ile sınırlayın. Önceki dosya işlenene kadar her iş parçacığında bekleyin ve ardından başka bir dosyayı karşıya yüklemek için iş parçacığını yeniden kullanabilirsiniz. Örneğin, bir iş parçacığı bir dosyayı karşıya yükleyebilir ve karşıya yükleme durumu Tamamlandı, CompletedWithErrors veya Başarısız olduktan sonra iş parçacığı başka bir dosyayı karşıya yükleyebilir.
Yalnızca eklediğiniz veya güncelleştirdiğiniz varlıkları ve alanları karşıya yükleyin. Sağlanırsa, teklif önerileri ve kalite puanı verileri gibi salt okunur alanlar yoksayılır.
Performansı en üst düzeye çıkarmak için dosya başına bir varlık türünü karşıya yükleyin. Örneğin yeni kampanyalar, reklamlar ve anahtar sözcükler oluştururken bunları başvuru anahtarlarıyla birlikte karşıya yüklemek daha verimli olabilir. Başka bir örnek olarak, yalnızca 10 kampanyayı, 500 reklamı ve 800 anahtar sözcüğü güncelleştiriyorsanız, bunları tür başına karşıya yüklemeleri bölmek yerine tek bir karşıya yüklemeye ekleyebilirsiniz.
Karşıya yükleme sonuçları dosyasında hata ve sonuç (ResponseMode = ErrorsAndResults) istemeniz gerekip gerekmediğini veya yalnızca hataların (ResponseMode = ErrorsOnly) yeterli olup olmayacağını göz önünde bulundurun. Sonuçları yerel verilerinizle eşitlemeniz gerekip gerekmediğini göz önünde bulundurun. Örneğin, varlıkları güncelleştiriyorsanız yalnızca herhangi bir hata oluşup oluşmadığını bilmeniz gerekebilir ve bu durumda GetBulkUploadUrl isteğinde ResponseMode = ErrorsOnly belirtebilirsiniz. Yeni varlıklar ekliyorsanız, sonuçta elde edilen varlık tanımlayıcılarını almak için GetBulkUploadUrl isteğinde ResponseMode = ErrorsAndResults belirtebilirsiniz.
Kısmi yeniden deneme denemelerinde, kayıtların yalnızca bir alt kümesi hatalarla sonuçlanırsa dosyanın tamamını karşıya yüklemeyin. Yalnızca yeniden denemek istediğiniz kayıtları karşıya yükleyin.
Karşıya yükleme durumu Completed, CompletedWithErrors veya Failed olana kadar yeniden denemeyin. Şans eseri performans beklentileri karşılamıyorsa, yine de sonucu bekleyin.
Makul aralıklarla karşıya yükleme sonuçlarını yoklama. Başlangıçta karşıya yüklenen her 10 bin satır için bir dakika beklemeniz gerekir. İlk bekleme süresinden sonra bir dakikalık aralıklarla yoklamayı göz önünde bulundurun.