Rapor ayarlarını yapılandırma

Makale
09/17/2023

Power BI İstemci API'lerini kullanarak Uygulamanıza Power BI analizi ekleyebilirsiniz. Bir 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ğlayın

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 rapor eklemeyi gösteren kod örnekleri için bkz. Rapor ekleme.

Ayarları özelleştirme

Aşağıdaki bölümlerde, ekli Power BI raporunuzun görünümünü ve davranışını ayarlamak için özelliğini nasıl kullanabileceğiniz settings açıklanmaktadır. Rapor zaten yüklendiğinde rapor ayarlarını güncelleştirmek için yöntemini kullanın report.updateSettings . 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 panes bir özellikle 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ğin hangi değerleri desteklediğini görebilirsiniz:

Özellik	Görünür	Genişletildi
`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 özelliğini kullanın filterPaneEnabled :

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

Not

Panes özelliği özelliğinfilterPaneEnabled yerini alır. Geriye dönük uyumluluğu filterPaneEnabled korumak için özelliği hala mevcuttur. 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 özelliğini kullanın navContentPaneEnabled :

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

Not

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

Sayfa gezinti bölmesi raporun en altında görünür; yeni dikey sayfalar bölmesini kullanmak için özelliğini ayarlayabilirsiniz position :

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

Not

kullanarak updateSettingssayfa gezinti bölmesinin konumunu değiştiremezsiniz.

Bar

özelliğini kullanarak eylem çubuğunun ve durum çubuğunun bars 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 URL parametresini actionBarEnabled kullanmak da mümkündür:

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

Not

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

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

Durum çubuğu

Durum çubuğu, tuval üzerinde yakınlaştırma olanağı sağlayan tuval yakınlaştırma denetleyicisini barındırıyor.

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

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

Yerel ayar ayarları

Eklenmiş raporun localeSettings dilini ve biçimlendirmesini belirtmek için özelliğini kullanın:

language içindeki localeSettings ö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 en (İngilizce), es (İspanyolca) ve tr (Türkçe) verilebilir.
locale , 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, bunlara localeSettingsbelirli bir değer 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 çağrısı yaparak powerbi.reset(element)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. Öğenin div stili daha sonra 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ı aşağıda listelenmiştir:

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 bir dataHyperlinkClicked olay oluşturur.
RaiseEvent - URL'ye tıklamanın ve olayı tetiklemesinin dataHyperlinkClicked varsayılan davranışını engeller.

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

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

İlk dataHyperlinkClicked çalıştırma tablosu veya matris görsellerine köprü tıklandığında ve davranış ya RaiseEventda NavigateAndRaiseEvent olduğunda olay tetikleniyor.

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

Olayları işleme hakkında daha fazla bilgi için bkz. Olayları işleme.

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.

Olayları tetiklemesini sağlamak visualRendered için bu kodu kullanın:

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

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

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

Olayları işleme hakkında daha fazla bilgi için bkz. Olayları işleme.

Not

Görseller kullanıcı etkileşimlerinden dolayı işlenebileceği için, bu olayın yalnızca gerektiğinde açılabilmesi ö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 özelliğini kullanın hideErrors . Kodunuz daha sonra hata olaylarını uygulama tasarımınıza uygun ş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, eklenen Power BI raporunuzun görünümünü ve davranışını daha fazla özelleştirmek için ek özellikleri nasıl kullanabileceğiniz açıklanmaktadır.

Varsayılan sayfa

Ekli raporunuzun başlangıçta hangi sayfasının görüneceğini denetleyebilirsiniz. Varsayılan olarak, ilk sayfa en son değiştirdiğiniz sayfadır ve bu, raporu son kaydettiğinizde etkin sayfadır. özelliğini kullanarak pageName ve görüntülemek istediğiniz sayfanın adıyla 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 ek filtreler yapılandırın. Aşağıdaki kod ek filtreler eklemek için özelliğinin filters nasıl kullanılacağını gösterir:
```
let embedConfig = {
    ...
    filters: [...]
};
```
Kaydedilen filtreleri yeni bir kümeyle değiştirin. yöntemi, setFilters bir raporun filtrelerini dinamik olarak değiştirmek için bir yol 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 yöntemini kullanma setFilters hakkında daha fazla bilgi için bkz. Rapor filtrelerini denetleme.

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 slicers gösterildiği gibi mevcut dilimleyicilerin durumunu değiştirmek için özelliğini kullanabilirsiniz:

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

Dilimleyicinin durumunu değiştirme hakkında daha fazla bilgi için bkz. Rapor dilimleyicilerini denetleme.

Yer işaretini yüklerken

özelliğini kullanarak bookmark , 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 iş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 türündedir IApplyBookmarkRequest. 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, bir yer işaretinin duruma göre nasıl belirtileceğini gösterir:

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

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

Eklenmiş 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 tema 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ı aşağıda listelenmiştir:

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 Nonenasıl geçersiz kılınacak olduğunu gö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 ayarı yoksayar theme .

Yakınlaştırma düzeyi

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

Düzenleme modunda aç

Varsayılan olarak, eklediğiniz rapor görüntüleme 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 özelliğini özelliğiyle permissions birlikte kullanınviewMode.

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

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

Özelliğine permissions ş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ı Kaydet'i kullanarak 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 permissions gösterildiği gibi özelliğine düzenlemeye uygun bir değer atayın:

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

Not

permissions Yapılandırdığınız değer 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");

Önemli noktalar ve sınırlamalar

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

Eylem çubuğu görünür olduğunda sayfa gezinti konumu değiştirilemez. Eylem çubuğu hakkında daha fazla bilgi edinin.
Çubuklar'da açıklandığı gibi özelliği özelliğinde setting kullandığınızdabars, API yalnızca eklenmiş içerik düzenleme modundaysa yapılandırmanızı uygular. İçeriğiniz görüntüleme modundaysa API ayarı yoksayar bars .
düzenleme modunda içerik görüntülemek için özelliğini kullandığınızda viewMode iki ek adım uygulamanız gerekir:
- özelliğiyle permissions 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, kullanıcının bir permissions değerini Read, atarsanız içerik düzenlenemez.
- Oluşturduğunuz ekleme belirtecinin düzenlemeyi destekleyen ayrıcalıklara sahip olduğundan emin olun. Örneğin, API değerine view, sahip bir accessLevel belirteç alırsanız içerik düzenleme modunda görüntülenemez.
Panes özelliği aşağıdaki settings özelliklerin yerini alır:
- filterPaneEnabled
- navContentPaneEnabled
Filtre veya sayfa gezintisi görünürlüğünü yapılandırmak için özelliğini kullanırsanızpanes, uygulamanızda veya navContentPaneEnabled özelliğini kullanmayınfilterPaneEnabled.
API, eklenmiş içeriğe aynı anda tema ve karşıtlık düzeyi uygulayamaz. ve contrastMode özelliklerini kullanarak theme her iki seçeneği de yapılandırırsanız, API ekli içerikle değerinizi contrastMode kullanır. Ancak API ayarı yoksayar theme .
Eklenmiş bir rapora yer işareti uygulamak istiyorsanız özelliğini kullanabilirsiniz bookmark . Bu özelliğe bir yer işareti adı eklerseniz, API yalnızca bu ada sahip bir yer işareti varsa yer işaretini kullanabilir. Benzer şekilde, bir açılış sayfası belirtmek için özelliğini kullanırsanız pageName , API bu sayfayı yalnızca verilen ada sahip bir sayfa varsa görüntüleyebilir. Bir adı yapılandırmadan önce, bir bileşenin bu adla var olup olmadığını denetlemek için Report getPages yöntemi gibi bir erişimci yöntemi kullanmayı göz önünde bulundurun.