Rapor ayarlarını yapılandırma

Makale
07/17/2024

Power BI İstemci API'lerini kullanarak Uygulamanıza Power BI analizi ekleyebilirsiniz. Power BI raporu eklemek için bu istemci tarafı kitaplığını kullandığınızda, API'ye bu raporla ilgili bilgileri sağlarsınız.

Power BI raporunuz hakkındaki bilgileri depolamak için bir yapılandırma nesnesi kullanabilirsiniz. Raporu eklediğinizde, bu nesneyi API'ye geçirirsiniz.

API'ye rapora erişim vermenin yanı sıra, raporunuzun görünümünü ve davranışını özelleştirmek için yapılandırma nesnesini de kullanabilirsiniz. Örneğin, yapılandırma nesnesinde filtre görünürlüğünü, gezinti erişimini ve konum ayarlarını ayarlayabilirsiniz.

Aşağıdaki bölümlerde Power BI içeriğini ekleme ve yapılandırma açıklanmaktadır.

Yapılandırma bilgilerini sağlama

IReportLoadConfiguration arabirimi, bir yapılandırma nesnesinin bir rapor hakkında Power BI İstemci API'lerine sağlayabildiği özellikleri görüntüler:

interface IReportLoadConfiguration {
    embedUrl: string;
    accessToken: string;
    id: string;
    groupId?: string;
    settings?: ISettings;
    bookmark?: IApplyBookmarkRequest;
    pageName?: string;
    filters?: ReportLevelFilters[];
    slicers?: ISlicer[];
    theme?: IReportTheme;
    contrastMode?: ContrastMode;
    datasetBinding?: IDatasetBinding;
    permissions?: Permissions;
    viewMode?: ViewMode;
    tokenType?: TokenType;
}

Bu arabirimin gerekli parametrelerinin açıklaması ve raporun nasıl eklendiğini gösteren kod örnekleri için bkz. Rapor ekleme .

Ayarları özelleştirme

Aşağıdaki bölümlerde, eklenmiş Power BI raporunuzun görünümünü ve davranışını ayarlamak için settings özelliğini nasıl kullanabileceğiniz açıklanmaktadır. Rapor zaten yüklendiğinde rapor ayarlarını güncelleştirmek için report.updateSettings yöntemini kullanın. Daha fazla bilgi için bkz.çalışma zamanında rapor ayarlarını güncelleştirme .

Bölme

Aşağıdaki kodda gösterildiği gibi, Power BI raporunuzdaki tüm bölmelerin görünümünü tek bir panes özelliğiyle denetleyin:

let embedConfig = {
    ...
    settings: {
        panes: {
            bookmarks: {
                visible: true
            },
            fields: {
                expanded: false
            },
            filters: {
                expanded: false,
                visible: true
            },
            pageNavigation: {
                visible: false
            },
            selection: {
                visible: true
            },
            syncSlicers: {
                visible: true
            },
            visualizations: {
                expanded: false
            }
        }
    }
};

Aşağıdaki tabloda, her panes özelliğinin hangi değerleri desteklediğini görebilirsiniz:

Mülk	Görünür	Genişletilmiş
`bookmarks`	✔	❌
`fields`	✔	✔
`filters`	✔	✔
`pageNavigation`	✔	❌
`selection`	✔	❌
`syncSlicers`	✔	❌
`visualizations`	✔	✔

Filtre bölmesi

Varsayılan olarak, filtre bölmesi görünür durumdadır. Bu bölmeyi gizlemek istiyorsanız, aşağıdaki kodda gösterildiği gibi filterPaneEnabled özelliğini kullanın:

let embedConfig = {
    ...
    settings: {
        filterPaneEnabled: false
    }
};

Not

panes özelliğifilterPaneEnabled özelliğinin yerini alır. Geriye dönük uyumluluğu korumak için filterPaneEnabled özelliği hala var. Ancak, bu iki özelliği birlikte kullanmaktan kaçınmalısınız.

Varsayılan olarak, sayfa gezinti okları eklenmiş raporlarda görünür. Bu okları gizlemek için aşağıdaki kodda gösterildiği gibi navContentPaneEnabled özelliğini kullanın:

let embedConfig = {
    ...
    settings: {
        navContentPaneEnabled: false
    }
};

Not

panes özelliğinavContentPaneEnabled özelliğinin yerini alır. Geriye dönük uyumluluğu korumak için navContentPaneEnabled özelliği hala var. Ancak, bu iki özelliği birlikte kullanmaktan kaçınmalısınız.

Raporun alt kısmında sayfa gezinti bölmesi görüntülenir; yeni dikey sayfalar bölmesini kullanmak için position özelliğini ayarlayabilirsiniz:

let embedConfig = {
    ...
    settings: {
        panes:{
            pageNavigation: {
                visible: true,
                position: PagesPosition.Left
            }
        }    
    }
};

Not

updateSettingskullanarak sayfa gezinti bölmesinin konumunu değiştiremezsiniz.

Bar

bars özelliğini kullanarak eylem çubuğunun ve durum çubuğunun görünürlüğünü ayarlayın.

Eylem çubuğu

Aşağıdaki kod eylem çubuğunu görünür hale getirir:

let embedConfig = {
    ...
    settings: {
        bars: {
            actionBar: {
                visible: true
            }
        }
    }
};

Alternatif olarak, görünüm modunda actionBarEnabled URL parametresini de kullanabilirsiniz:

let embedConfig = {
   ...
   embedUrl: embedUrl + "&actionBarEnabled=true"
};

Not

Görünüm modunda eylem çubuğu yalnızca kuruluşunuz senaryosu için ekleme için desteklenir.

Görünüm modundaki eylem çubuğu için Azure AD uygulamanız için UserState.ReadWrite.All iznini etkinleştirmeniz önerilir. Bu izin, son kullanıcıların raporu sık kullanılanlarına eklemesine izin vermek ve kişisel yer işaretlerini etkinleştirmek vekalıcı filtreleri için gereklidir.

Durum çubuğu

Durum çubuğu, tuvali yakınlaştırma olanağı sağlayan tuval yakınlaştırma denetleyicisini tutar.

Aşağıdaki kod durum çubuğunu görünür hale getirir:

let embedConfig = {
    ...
    settings: {
        bars: {
            statusBar: {
                visible: true
            }
        }
    }
};

Yerel ayar ayarları

Katıştırılmış raporun dilini ve biçimlendirmesini belirtmek için localeSettings özelliğini kullanın:

localeSettings'daki language özelliği, her biri kısa çizgiyle ayrılmış iki harfli iki bölümden oluşur:

dil, Power BI'ın yerelleştirme için kullandığı dili tanımlar. Dillere örnek olarak (İngilizce), es (İspanyolca) ve tr (Türkçe) verilebilir.
yerel ayar Power BI'ın tarihler, para birimi ve diğer ilgili içerik için kullandığı metin biçimlendirmesini tanımlar. Yerel ayarlara örnek olarak ABD (İngilizce), ES (İspanya) ve TR (Türkiye) verilebilir.

Kullanılabilir dillerin ve bölgelerin listesi için bkz. Desteklenen diller.

Aşağıdaki kod bu localeSettingsbelirli değerler atar:

let embedConfig = {
    ...
    settings: {
        localeSettings: {
            language: "en-us"
        }
    }
};

Not

Rapor yüklendikten sonra yerel ayar ayarları değiştirilemez. Rapor yerel ayarı ayarlarını değiştirmek için powerbi.reset(element)çağırarak iframe'i sıfırlayın ve raporu yeniden ekleyin.

Saydam arka plan

Varsayılan olarak, eklenmiş içeriğin arka planı gri kenar boşluklarıyla beyazdır. İsterseniz, eklenmiş içeriğe saydam bir arka plan verebilirsiniz. Ardından, istediğiniz stili eklenmiş içeriği içeren HTML div öğesine uygulayabilirsiniz. div öğesinin stili görünür hale gelir.

Eklenen içeriğin arka planını saydam hale getirmek için bu kodu kullanın:

let embedConfig = {
    ...
    settings: {
        background: models.BackgroundType.Transparent
    }
};

Köprü tıklama davranışı

Bir tablodaki köprü veya matrisin ilk çalıştırma görsellerindeki davranışını denetleyebilirsiniz. Varsayılan olarak, köprü yeni bir pencere açar.

Kullanılabilir davranış modları:

enum HyperlinkClickBehavior {
    Navigate,
    NavigateAndRaiseEvent,
    RaiseEvent
}

Navigate - URL yeni bir gözatma bağlamı içine yüklenir.
NavigateAndRaiseEvent - URL yeni bir gözatma bağlamı içine yüklenir ve dataHyperlinkClicked bir olay oluşturur.
RaiseEvent - URL'ye tıklamanın varsayılan davranışını engeller ve dataHyperlinkClicked olayı tetikler.

Olay oluşturacak bağlantıların davranışını değiştirmek için bu kodu kullanın:

let embedConfig = {
    ...
    settings: {
        hyperlinkClickBehavior: HyperlinkClickBehavior.RaiseEvent
    }
};

bir dataHyperlinkClicked olayı, kullanıma açık bir tablo veya matris görselinde köprüye tıklandığında ve davranış NavigateAndRaiseEvent veya RaiseEventolduğunda tetikler.

report.on('dataHyperlinkClicked', () => {
    ...
});

Olayları işleme hakkında daha fazla bilgi için olayları işleme bölümüne bakın.

Görsel işlenmiş olaylar

İşlenen her görsel için bir olayı dinleyebilirsiniz. Varsayılan olarak, işlenen görsel olaylar devre dışı bırakılır.

visualRendered olaylarının tetiklendirilmesi için bu kodu kullanın:

let embedConfig = {
    ...
    settings: {
        visualRenderedEvents: true
    }
};

Bir görsel işlendiğinde ve rapor ayarlarında visualRenderedEvents etkinleştirildiğinde bir visualRendered olayı tetikler.

report.on('visualRendered', () => {
    ...
});

Olayları işleme hakkında daha fazla bilgi için olayları işleme bölümüne bakın.

Not

Görseller kullanıcı etkileşimleri nedeniyle işlenebileceği için bu olayı yalnızca gerektiğinde açmanız önerilir.

Hata iletileri

Eklenen raporlarda özelleştirilmiş hata iletileri görüntülemek istiyorsanız, varsayılan Power BI eklenmiş hata iletilerini gizlemek için hideErrors özelliğini kullanın. Kodunuz daha sonra hata olaylarını uygulama tasarımınıza uygun bir şekilde işleyebilir. Varsayılan hataları geçersiz kılma hakkında daha fazla bilgi için bkz. Varsayılan hata iletilerini geçersiz kılma.

Varsayılan hata iletilerini gizlemek için bu kodu kullanın:

let embedConfig = {
    ...
    settings: {
        hideErrors: true
    }
};

Seçenekleri özelleştirme

Aşağıdaki bölümlerde, ekli Power BI raporunuzun görünümünü ve davranışını daha fazla özelleştirmek için daha fazla özelliği nasıl kullanabileceğiniz açıklanmaktadır.

Varsayılan sayfa

Başlangıçta eklenmiş raporunuzun hangi sayfasının görüneceğini denetleyebilirsiniz. Varsayılan olarak, ilk sayfa en son değiştirdiğiniz sayfadır ve raporu en son kaydettiğinizde etkin olan sayfadır. pageName özelliğini kullanarak ve görüntülemek istediğiniz sayfanın adını sağlayarak bu davranışı geçersiz kılabilirsiniz. Ancak Power BI'da bu ada sahip bir sayfa yoksa, sayfayı açma isteği başarısız olur.

Aşağıdaki kod, uygulamanızı belirli bir sayfayı görüntüleyecek şekilde yapılandırmayı gösterir:

let embedConfig = {
    ...
    pageName: 'ReportSection3'
};

Yük filtrelerinde

Uygulamanızın eklenmiş bir rapora uyguladığı filtreleri denetleyebilirsiniz. Varsayılan olarak, rapor başlangıçta rapora kaydettiğiniz filtreleri kullanır. Ancak, filtreleri ayarlamak istiyorsanız iki seçeneğiniz vardır:

Kaydedilen filtrelerle birlikte kullanmak için daha fazla filtre yapılandırın. Aşağıdaki kod, daha fazla filtre eklemek için filters özelliğinin nasıl kullanılacağını gösterir:
```
let embedConfig = {
    ...
    filters: [...]
};
```
Kaydedilen filtreleri yeni bir kümeyle değiştirin. setFilters yöntemi, raporun filtrelerini dinamik olarak değiştirmenin bir yolunu sağlar. Aşamalı ekleme sırasında bu yöntemi kullanırsanız, raporun başlangıçta uyguladığı filtreleri geçersiz kılabilirsiniz. Filtre oluşturma ve setFilters yöntemini kullanma hakkında daha fazla bilgi için bkz. Rapor filtrelerinidenetleme.

Yük dilimleyicilerde

Uygulamanızın eklenmiş bir rapora uyguladığı dilimleyicilerin durumunu denetleyebilirsiniz. Varsayılan olarak, API rapora kaydettiğiniz dilimleyicileri kullanır. Ancak, aşağıdaki kodda gösterildiği gibi mevcut dilimleyicilerin durumunu değiştirmek için slicers özelliğini kullanabilirsiniz:

embedConfig = {
    ...
    slicers: slicerArray,
};

Dilimleyicinin durumunu değiştirme hakkında daha fazla bilgi için bkz. Denetim raporu dilimleyicileri.

Yer işaretini yüklerken

bookmark özelliğini kullanarak eklenmiş bir rapora yer işareti uygulayabilirsiniz. Rapor sayfalarının şu anda yapılandırılmış görünümünü yakalamak için yer işaretlerini kullanma hakkında daha fazla bilgi için bkz. Yer İşaretleri.

Kullanılacak yer işaretini, yer işareti adını veya durumunu sağlayarak belirtebilirsiniz. Yer işareti adını sağlarsanız Power BI raporunuzun bu ada sahip kaydedilmiş bir yer işareti içermesi gerekir.

bookmark özelliği IApplyBookmarkRequest. türündedir. Aşağıdaki kod bu türün tanımını gösterir:

type IApplyBookmarkRequest = IApplyBookmarkStateRequest | IApplyBookmarkByNameRequest;

interface IApplyBookmarkStateRequest {
    state: string;
}

interface IApplyBookmarkByNameRequest {
    name: string;
}

Bu kod, bir yer işaretinin ada göre nasıl belirtileceğini gösterir:

let embedConfig = {
    ...
    bookmark: {
        name: "Bookmark4f76333c3ea205286501"
    }
};

Bu kod, duruma göre bir yer işaretinin nasıl belirtileceğini gösterir:

let embedConfig = {
    ...
    bookmark: {
        state: bookmarkState
    }
};

Temalar ve yüksek karşıtlık modu

Ekli içeriğinizin kullandığı tema ve karşıtlık düzeyini denetleyebilirsiniz. Varsayılan olarak, eklediğiniz tüm içerikler varsayılan temayla ve sıfır karşıtlıkla görüntülenir. Belirli bir temayı veya karşıtlık düzeyini yapılandırarak bu davranışı geçersiz kılabilirsiniz. Temalar hakkında daha fazla bilgi için bkz. rapor temalarını uygulama.

Kullanılabilir karşıtlık modları:

enum ContrastMode {
    None = 0,
    HighContrast1 = 1,
    HighContrast2 = 2,
    HighContrastBlack = 3,
    HighContrastWhite = 4
}

Belirli bir temayı yapılandırmak için aşağıdaki satırlara benzer bir kod kullanın:

let embedConfig = {
    ...
    theme: {themeJson: ...}
};

Aşağıdaki kod, varsayılan karşıtlık düzeyinin nasıl geçersiz kılınacak olduğunu Nonegösterir:

let embedConfig = {
    ...
    contrastMode: models.contrastMode.HighContrast1
};

Not

API bir temayı ve karşıtlık düzeyini aynı anda uygulayamaz. Her iki özelliği de yapılandırdığınızda, API belirttiğiniz karşıtlık düzeyini kullanır ancak theme ayarını yoksayar.

Yakınlaştırma düzeyi

Rapor yakınlaştırma düzeyini ayarlama hakkında daha fazla bilgi edinmek içinerişilebilirlik belgesini denetleyin.

Düzenleme modunda aç

Varsayılan olarak, eklediğiniz rapor görünüm modunda görünür. Ancak, raporu düzenleme modunda açmak için bu davranışı geçersiz kılabilirsiniz. Modlar arasında da geçiş yapabilirsiniz.

Düzenleme modunu yapılandırma

Eklenmiş bir raporu düzenleme modunda açmak için permissions özelliğiyle birlikte viewMode özelliğini kullanın.

viewMode özelliğine aşağıdaki değerleri atayabilirsiniz:

View - Raporu görüntüleme modunda açar.
Edit - Raporu düzenleme modunda açar.

permissions özelliğine şu değerleri atayabilirsiniz:

Read - Kullanıcılar raporu görüntüleyebilir.
ReadWrite - Kullanıcılar raporu görüntüleyebilir, düzenleyebilir ve kaydedebilir.
Copy - Kullanıcılar Farklı Kaydetkullanarak raporun bir kopyasını kaydedebilir.
Create - Kullanıcılar yeni bir rapor oluşturabilir.
All - Kullanıcılar raporun bir kopyasını oluşturabilir, görüntüleyebilir, düzenleyebilir, kaydedebilir ve kaydedebilir.

İçeriği düzenleme modunda açılacak şekilde yapılandırdığınızda, aşağıdaki kodda gösterildiği gibi permissions özelliğine düzenlemeye uygun bir değer atayın:

let embedConfig = {
    ...
    permissions: models.Permissions.All
    viewMode: models.ViewMode.Edit
};

Not

Yapılandırdığınız permissions değeri yalnızca aldığınız ekleme belirtecinin yeterli ayrıcalıklara sahip olması durumunda çalışır. Ekleme belirteçleri hakkında daha fazla bilgi için bkz. ekleme belirtecini oluşturma.

Düzenleme ve görüntüleme modları arasında geçiş yapma

Eklenen içeriğin başlaması için bir mod belirtmenin yanı sıra düzenleme ve görüntüleme modları arasında dinamik olarak geçiş de yapabilirsiniz.

İçerik düzenleme modundaysa ve görüntüleme moduna geçmek istiyorsanız şu JavaScript kodunu kullanın:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to view mode.
embeddedContent.switchMode("view");

İçerik görüntüleme modundaysa ve düzenleme moduna geçmek istiyorsanız şu JavaScript kodunu kullanın:

// Embed the content.
let embeddedContent = powerbi.embed(container, embedConfiguration);

...

// Switch to edit mode.
embeddedContent.switchMode("edit");

Dikkat edilmesi gerekenler ve sınırlamalar

Eklenmiş içeriği yapılandırırken aşağıdaki noktaları göz önünde bulundurun:

sayfa gezinti konumu, eylem çubuğu görünür olduğunda değiştirilemez. eylem çubuğu hakkında daha fazla bilgi edinin.
setting özelliğinde bars özelliğini kullandığınızda, Çubukları'de açıklandığı gibi, API yalnızca eklenmiş içerik düzenleme modundaysa yapılandırmanızı uygular. İçeriğiniz görüntüleme modundaysa, API bars ayarını yoksayar.
İçeriği düzenleme modunda görüntülemek için viewMode özelliğini kullandığınızda iki ek adım uygulamanız gerekir:
- permissions özelliğiyle bir izin düzeyi yapılandırın. Bu izin düzeyinin kullanıcıya içeriği değiştirmek için uygun erişim vermesi gerekir. Örneğin, Read,permissions değeri atarsanız kullanıcı içeriği düzenleyemez.
- oluşturduğunuz ekleme belirtecinin düzenlemeyi destekleyen ayrıcalıklara sahip olduğundan emin olun. Örneğin, accessLevel değeri view, olan bir belirteç alırsanız API içeriği düzenleme modunda görüntüleyemiyor.
panes özelliği aşağıdaki settings özelliklerinin yerini alır:
- filterPaneEnabled
- navContentPaneEnabled
filtre veya sayfa gezinti görünürlüğünü yapılandırmak için panes özelliğini kullanıyorsanız, uygulamanızdaki filterPaneEnabled veya navContentPaneEnabled özelliğini kullanmayın.
API, eklenmiş içeriğe aynı anda tema ve karşıtlık düzeyi uygulayamaz. her iki seçeneği de theme ve contrastMode özelliklerini kullanarak yapılandırdığınızda, API ekli içerikle contrastMode değerinizi kullanır. Ancak API, theme ayarını yoksayar.
Eklenmiş bir rapora yer işareti uygulamak istiyorsanız bookmark özelliğini kullanabilirsiniz. Bu özelliğe sahip bir yer işareti adı verirseniz, API yalnızca bu ada sahip bir yer işareti varsa yer işaretini kullanabilir. Benzer şekilde, bir açılış sayfası belirtmek için pageName özelliğini kullanırsanız, API bu sayfayı yalnızca verilen ada sahip bir sayfa varsa görüntüleyebilir. Bir adı yapılandırmadan önce, Report getPages yöntemigibi bir erişimci yöntemi kullanarak bu ada sahip bir bileşenin mevcut olup olmadığını denetleyin.

Yer işaretleri kullanıcılarınızın deneyimini geliştirme
Power BI'da rapor temaları uygulama
Denetim raporu filtreleri
rapor dilimleyicilerini

Aracılığıyla paylaş

Rapor ayarlarını yapılandırma

Yapılandırma bilgilerini sağlama

Ayarları özelleştirme

Bölme

Filtre bölmesi

Sayfa gezinti bölmesi

Bar

Eylem çubuğu

Durum çubuğu

Yerel ayar ayarları

Saydam arka plan

Köprü tıklama davranışı

Görsel işlenmiş olaylar

Hata iletileri

Seçenekleri özelleştirme

Varsayılan sayfa

Yük filtrelerinde

Yük dilimleyicilerde

Yer işaretini yüklerken

Temalar ve yüksek karşıtlık modu

Yakınlaştırma düzeyi

Düzenleme modunda aç

Düzenleme modunu yapılandırma

Düzenleme ve görüntüleme modları arasında geçiş yapma

Dikkat edilmesi gerekenler ve sınırlamalar

Ek kaynaklar

Aracılığıyla paylaş

Rapor ayarlarını yapılandırma

Yapılandırma bilgilerini sağlama

Ayarları özelleştirme

Bölme

Filtre bölmesi

Sayfa gezinti bölmesi

Bar

Eylem çubuğu

Durum çubuğu

Yerel ayar ayarları

Saydam arka plan

Köprü tıklama davranışı

Görsel işlenmiş olaylar

Hata iletileri

Seçenekleri özelleştirme

Varsayılan sayfa

Yük filtrelerinde

Yük dilimleyicilerde

Yer işaretini yüklerken

Temalar ve yüksek karşıtlık modu

Yakınlaştırma düzeyi

Düzenleme modunda aç

Düzenleme modunu yapılandırma

Düzenleme ve görüntüleme modları arasında geçiş yapma

Dikkat edilmesi gerekenler ve sınırlamalar

İlgili içerik

Ek kaynaklar