職場のコラボレーションは、多くの場合、organization を超えて外部パートナーにまで及びます。 organizationのネットワークの外部で情報を共有するには、データ損失を防止し、コンプライアンスポリシーを適用するための対策が必要です。 Microsoft Purview Information Protection は、機密情報を分類および保護するためのソリューションを提供します。 秘密度ラベルは、この保護を Excel、Outlook、PowerPoint、Word のデータに適用します。
Office JavaScript API を使用して、Office アドイン プロジェクトに秘密度ラベル ソリューションを実装し、次のシナリオをサポートします。
- ドキュメント、メッセージ、予定に秘密度ラベルを適用して、ビジネス ポリシーと法的ポリシーに準拠します。
- ユーザーがメッセージに外部受信者を追加できないようにするなど、特定の秘密度ラベルが適用されている場合は追加のアクションを制限します。
- 監査とレポートをサポートするために、秘密度ラベルに基づいてデータを分類します。
注:
Excel、PowerPoint、Word では、秘密度ラベル API はプレビュー段階です。 Outlook では、秘密度ラベル機能のサポートは要件 セット 1.13 で導入されました。 クライアント サポートの詳細については、「 サポートされるクライアントとプラットフォーム」を参照してください。
前提条件
秘密度ラベル機能には、Microsoft 365 E5 サブスクリプションが必要です。 プログラム FAQ の Microsoft 365 開発者プログラムを通じて、Microsoft 365 E5 開発者サブスクリプションの資格があるかどうかを確認します。 それ以外の場合は、 1 か月間の無料試用版を開始する か、 Microsoft 365 プランを購入します。
サポートされているクライアントとプラットフォーム
秘密度ラベル API のサポートは、Office アプリケーションとプラットフォームによって異なります。 Outlook のサポートには Exchange Online が必要です。 次の表は、サポートされている組み合わせの一覧です。
| アプリケーション | Web | Windows | Mac |
|---|---|---|---|
| Excel | Preview | プレビュー | Preview |
| Outlook | サポート | サポート (新規およびクラシック (バージョン 2304 (ビルド 16327.20248) 以降)) |
サポート (バージョン 16.77 (23081600) 以降) |
| PowerPoint | Preview | プレビュー | Preview |
| Word | Preview | プレビュー | Preview |
秘密度ラベルのサポートを構成する
注:
プレビュー API は変更される可能性があり、運用環境での使用を目的としたものではありません。 試用はテスト環境と開発環境に限定することをお勧めします。 運用環境またはビジネス クリティカルなドキュメント内でプレビュー API を使用しないでください。
プレビュー API を使用するには:
-
Office.js コンテンツ配信ネットワーク (CDN) から Office JavaScript API ライブラリのプレビュー版を使用する必要があります。 TypeScript コンパイルおよび IntelliSense の 型定義ファイルは CDN で見つかり、DefinitelyTyped にあります。 これらの型は、
npm install --save-dev @types/office-js-previewを使用してインストールできます。 - 最新の Office ビルドにアクセスするには、 Microsoft 365 Insider Program への参加が必要な場合があります。
Excel、PowerPoint、Word 秘密度ラベル API も同様のプログラミング パターンに従います。 各ホストでは、要求コンテキストは秘密度ラベル カタログへのアクセスを提供し、ホスト固有のファイル オブジェクトはラベルを取得または更新するメソッドを提供します。
次の表に、秘密度ラベル カタログへのアクセスに使用される API メンバーと、各 Office ホスト アプリケーションのファイルに適用されているラベルを示します。
| アプリケーション | 秘密度ラベル カタログ | ファイルの秘密度ラベル |
|---|---|---|
| Excel | context.sensitivityLabelsCatalog |
context.workbook.sensitivityLabel |
| PowerPoint | context.sensitivityLabelsCatalog |
context.presentation.sensitivityLabel |
| Word | context.sensitivityLabelsCatalog |
context.document.sensitivityLabel |
次のセクションの例では Word を使用します。 Excel または PowerPoint を使用するには、対応するホスト名前空間とファイル レベルの秘密度ラベル オブジェクトに置き換えます。
Script Lab で API を試してみる
Script Lab アドインを取得して、Office アプリケーションの秘密度ラベルの管理サンプルを試してください。
サンプルでは、ラベル付け機能のチェック、ラベルとサブラベルの一覧表示、ABAC 属性の取得、現在のラベルの取得、ABAC 属性の有無にかかわらずラベルを適用する方法を示します。
Script Lab の詳細については、「Script Lab を使用して Office JavaScript API を探索する」を参照してください。
秘密度ラベル付けが利用可能であることを確認する
秘密度ラベルとポリシーは、Microsoft Purview コンプライアンス ポータルを通じてorganizationの管理者によって構成されます。 テナントで秘密度ラベルを構成する方法のガイダンスについては、「 秘密度ラベルとそのポリシーの作成と構成」を参照してください。
現在のユーザーが秘密度ラベル付けを使用できるかどうかを判断するには、秘密度ラベル カタログから getLabelingCapability (Excel、PowerPoint、Word) を読み込みます。
状態は、labelingEnabled、labelingDisabled、labelingPolicyNotFound、noLicense などのLabelingCapability値 (Excel、PowerPoint、Word) です。 追加の機能チェックには、getLabelingCapabilities 配列 (Excel、PowerPoint、Word) を読み込みます。 たとえば、属性ベースのアクセス制御 (ABAC) 属性を取得する前にattributeBasedAccessControlEnabledをチェックします。
await Word.run(async (context) => {
// Access the sensitivity label catalog for the current user.
const labelCatalog = context.sensitivityLabelsCatalog;
if (!labelCatalog) {
console.warn("The sensitivity label catalog isn't available.");
return;
}
// Load the labeling capability status before reading it.
labelCatalog.load("getLabelingCapability,getLabelingCapabilities");
await context.sync();
// Display whether sensitivity labeling is enabled and available.
console.log(`Sensitivity labeling capability: ${labelCatalog.getLabelingCapability}`);
console.log("Available labeling capabilities:", labelCatalog.getLabelingCapabilities);
});
使用可能な秘密度ラベルを識別する
現在のユーザーに発行されているラベルを取得するには、カタログで getLabels() (Excel、PowerPoint、Word) を呼び出します。
このメソッドは、明示的に読み込んで context.sync() を呼び出すまでアイテムとプロパティを使用できないコレクションを返します。 ガイダンスについては、「 コレクションから読み込む」を参照してください。 アドインに必要な items とラベル プロパティを読み込みます。
SensitivityLabelDetails オブジェクト (Excel、PowerPoint、Word) は、次の情報を提供します。
- ラベルの ID、名前、説明 (
tooltip)、色、順序、テナント ID (siteId)。 - ラベルが有効かどうか (
isEnabled) および保護の種類 (protectionType)。 -
childrenコレクションのサブラベル。 アドインに必要なサブラベルのプロパティを明示的に読み込みます。 - ラベルが ABAC (
isAbacEnabled) をサポートし、属性の選択 (isAbacAttributesRequired) が必要かどうか。
await Word.run(async (context) => {
// Access the sensitivity label catalog for the current user.
const labelCatalog = context.sensitivityLabelsCatalog;
if (!labelCatalog) {
console.warn("The sensitivity label catalog isn't available.");
return;
}
// Get the available labels and load the properties used by the add-in.
const availableLabels = labelCatalog.getLabels();
availableLabels.load(
"items/id,items/name,items/isEnabled,items/isAbacEnabled,items/isAbacAttributesRequired," +
"items/children/items/id,items/children/items/name,items/children/items/isEnabled"
);
await context.sync();
// Display the available labels.
console.log("Available sensitivity labels:");
availableLabels.items.forEach((label) => {
console.log(`${label.name} (${label.id}) - ${label.isEnabled ? "Enabled" : "Disabled"}`);
console.log(`ABAC enabled: ${label.isAbacEnabled}; attributes required: ${label.isAbacAttributesRequired}`);
if (label.children) {
label.children.items.forEach((sublabel) => {
console.log(` ${sublabel.name} (${sublabel.id}) - ${sublabel.isEnabled ? "Enabled" : "Disabled"}`);
});
}
});
});
秘密度ラベルを取得する
現在のラベルが適用されている場合は、それを取得するには、ファイルの秘密度ラベル オブジェクトで getCurrentOrNullObject() (Excel、PowerPoint、Word) を呼び出します。
await Word.run(async (context) => {
// Access the sensitivity label applied to the current document.
const documentLabel = context.document.sensitivityLabel;
// Get the current label, if one is applied.
const currentLabel = documentLabel.getCurrentOrNullObject();
currentLabel.load("id,name,isAbacEnabled");
await context.sync();
// Display the current label or report that the document isn't labeled.
if (currentLabel.isNullObject) {
console.log("The document doesn't have a sensitivity label.");
} else {
console.log(`Current label: ${currentLabel.name} (${currentLabel.id})`);
if (currentLabel.isAbacEnabled) {
currentLabel.load("abacAttributeValues");
await context.sync();
console.log("Applied ABAC attribute values:", currentLabel.abacAttributeValues);
}
}
});
秘密度ラベルを設定します
ラベルを適用する前に、getLabels() (Excel、PowerPoint、Word) を呼び出し、返されたコレクションから有効なラベルまたはサブラベルを選択します。
tryToUpdate() メソッド (Excel、PowerPoint、Word) では、最初のパラメーターとして選択したラベルの ID が必要であり、ABAC 属性の選択にオプションの SensitivityLabelTryUpdateOptions オブジェクト (Excel、PowerPoint、Word) を受け入れます。 最初に getLabels() を呼び出すと、必要な ID を取得し、現在のユーザーがラベルを使用できることを確認できます。
context.sync() を呼び出した後、返された SensitivityLabelUpdateResult オブジェクト (Excel、PowerPoint、Word) からupdateResult.value.statusを読み取ります。
SensitivityLabelUpdateStatus.success (Excel、PowerPoint、Word) と比較して、更新が成功したかどうかを判断します。
注:
サブラベルを持つ親ラベルを直接適用することはできません。 有効になっているサブラベルの 1 つを代わりに選択します。
async function setDocumentSensitivityLabel(labelId: string, options?: Word.SensitivityLabelTryUpdateOptions) {
await Word.run(async (context) => {
// Access the sensitivity label applied to the current document.
const documentLabel = context.document.sensitivityLabel;
// Apply the selected label.
const updateResult = documentLabel.tryToUpdate(labelId, options);
await context.sync();
// Check whether the label update succeeded.
if (updateResult.value.status === Word.SensitivityLabelUpdateStatus.success) {
console.log("Applied the sensitivity label to the document.");
} else {
console.error(`The sensitivity label wasn't applied. Status: ${updateResult.value.status}`);
}
});
}
ABAC 属性を持つラベルを適用する
ABAC 対応ラベルの場合は、SensitivityLabelsCatalog.getAttributes() (Excel、PowerPoint、Word) を使用して使用可能な属性を取得します。 まず、 getLabelingCapabilities を読み込み、 LabelingCapability.attributeBasedAccessControlEnabledが含まれていることを確認します。 このメソッドは、value プロパティにSensitivityLabelAbacAttributeオブジェクト (Excel、PowerPoint、Word) の配列が含まれているClientResultを返します。 このプロパティを読み取る前に context.sync() を呼び出してください。
各属性には、表示名、表示順序、データ型、アクティブ状態、 isMultiValued フラグ、および values 配列があります。
await Word.run(async (context) => {
const labelCatalog = context.sensitivityLabelsCatalog;
if (!labelCatalog) {
console.warn("The sensitivity label catalog isn't available.");
return;
}
labelCatalog.load("getLabelingCapabilities");
await context.sync();
if (!labelCatalog.getLabelingCapabilities.includes(Word.LabelingCapability.attributeBasedAccessControlEnabled)) {
console.warn("ABAC attributes aren't enabled or available for the current user.");
return;
}
const catalogAttributes: OfficeExtension.ClientResult<Word.SensitivityLabelAbacAttribute[]> =
labelCatalog.getAttributes();
await context.sync();
console.log("Available ABAC attributes:", catalogAttributes.value);
});
ABAC 属性を含むラベルを適用するには、カタログの属性を使用し、ユーザーが選択した値のみを各属性の values 配列に含めます。 アクティブな属性とアクティブな値のみを使用し、 isMultiValued が trueされている場合にのみ複数の値を許可します。 ラベルを適用する前に、現在のポリシーに対して選択内容を検証します。
tryToUpdate() に提供されたオプション オブジェクトの abacAttributes プロパティを介して、選択した属性を渡します。 次の規則が適用されます。
-
isAbacEnabledがfalseの場合は、省略abacAttributesか、空の配列を渡します。 それ以外の場合、更新状態はabacAttributesNotAllowedです。 -
isAbacEnabledとisAbacAttributesRequiredの両方がtrue場合は、属性の選択を指定します。 それ以外の場合、更新状態はabacAttributesRequiredです。 - 更新プログラムの状態を調べて、
unsupportedAbac、labelDisabled、insufficientPermissionなど、他のエラーがないか確認します。context.sync()が完成したからといって、ラベルが適用されたことを意味するわけではありません。
現在ファイルに適用されている ABAC 値を読み取るには、「秘密度ラベルの取得」に示すように、getCurrentOrNullObject() によって返されるオブジェクトにabacAttributeValuesを読み込みます。 値を読み込む前に、 isNullObject と isAbacEnabled を確認してください。
OnSensitivityLabelChanged イベントを使用して秘密度ラベルの変更を検出する
注:
OnSensitivityLabelChanged イベントは Outlook でのみ使用できます。
OnSensitivityLabelChanged イベントを使用して、メッセージまたは予定の秘密度ラベルが変更されたときにアドイン ロジックを実行します。 たとえば、特定の添付ファイルを含むメール アイテムのラベルをユーザーがダウングレードできないようにします。
OnSensitivityLabelChanged イベントは、イベント ベースのアクティブ化を使用します。 構成、デバッグ、および展開のガイダンスについては、「 イベントを使用してアドインをアクティブ化する」を参照してください。
関連項目
Office Add-ins