Office アドインの秘密度ラベルを管理する

職場のコラボレーションは、多くの場合、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 を使用するには、対応するホスト名前空間とファイルレベルの秘密度ラベルオブジェクトに置き換えます。

Outlook アドインで秘密度ラベル機能を使用するには、アドインのマニフェストで アイテムの読み取り/書き込み アクセス許可を構成する必要があります。

Microsoft 365 の統合マニフェスト: "authorization.permissions.resourceSpecific" 配列で、オブジェクトの "name" プロパティを "MailboxItem.ReadWrite.User" に設定します。
アドイン専用マニフェスト: <Permissions> 要素を ReadWriteItem に設定します。

注:

Microsoft 365 の統合マニフェストを使用するアドインは、Outlook on Mac ではサポートされていません。 Microsoft はそのサポートを提供できるよう懸命に取り組んでいます。それまでの間、顧客ベースに Mac のユーザーが含まれる場合は、アドインのみのマニフェストを使用するバージョンのアドインを作成し、両方をサポートする必要があります。詳細については、「 Microsoft 365 の統合マニフェストを使用したアドインのサポート」を参照してください。

OnSensitivityLabelChanged イベントを処理するアドインには、イベントベースのアクティベーションのために追加のマニフェスト構成が必要です。詳細については、「 OnSensitivityLabelChanged イベントを使用して秘密度ラベルの変更を検出する」を参照してください。

秘密度ラベル付けが利用可能であることを確認する

秘密度ラベルとポリシーは、Microsoft Purview コンプライアンスポータルを通じてorganizationの管理者によって構成されます。テナントで秘密度ラベルを構成する方法のガイダンスについては、「秘密度ラベルとそのポリシーの作成と構成」を参照してください。

Excel、PowerPoint、および Word
Outlook

現在のユーザーが秘密度ラベル付けを使用できるかどうかを判断するには、秘密度ラベルカタログから getLabelingCapability (Excel、PowerPoint、Word) を読み込みます。

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");
    await context.sync();

    // Display whether sensitivity labeling is enabled and available.
    console.log(`Sensitivity labeling capability: ${labelCatalog.getLabelingCapability}`);
});

メッセージまたは予定で秘密度ラベルを取得または設定する前に、アドインがインストールされているメールボックスで秘密度ラベルカタログが有効になっていることを確認します。作成モードで context.sensitivityLabelsCatalog.getIsEnabledAsync を呼び出します。

// Check whether the catalog of sensitivity labels is enabled.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
        console.log(asyncResult.value);
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

使用可能な秘密度ラベルを識別する

Excel、PowerPoint、および Word
Outlook

現在のユーザーに発行されているラベルを取得するには、カタログで getLabels() (Excel、PowerPoint、Word) を呼び出します。

このメソッドは、明示的に読み込んで context.sync() を呼び出すまでアイテムとプロパティを使用できないコレクションを返します。ガイダンスについては、「コレクションから読み込む」を参照してください。アドインに必要な items とラベルプロパティを読み込みます。使用可能なプロパティはホストによって異なります。完全な一覧については、「SensitivityLabelDetails (Excel、PowerPoint、Word) を参照してください。

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");
    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"}`);
    });
});

作成モードのメッセージまたは予定で使用できる秘密度ラベルを決定するには、 context.sensitivityLabelsCatalog.getAsync を使用します。使用可能なラベルは、次の詳細を提供する SensitivityLabelDetails オブジェクトの形式で返されます。

ラベルの名前。
ラベルの一意識別子 (GUID)。
ラベルの説明。
ラベルに割り当てられた色。
構成済みのサブラベル (存在する場合)。

次の例は、カタログで使用可能な秘密度ラベルを識別する方法を示しています。

// Check the sensitivity label catalog status before calling other label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Identify available sensitivity labels in the catalog.
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                console.log("Sensitivity Labels Catalog:");
                catalog.forEach((sensitivityLabel) => {
                    console.log(`Name: ${sensitivityLabel.name}`);
                    console.log(`ID: ${sensitivityLabel.id}`);
                    console.log(`Tooltip: ${sensitivityLabel.tooltip}`);
                    console.log(`Color: ${sensitivityLabel.color}`);
                    console.log(`Sublabels: ${JSON.stringify(sensitivityLabel.children)}`);
                });
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

秘密度ラベルを取得する

Excel、PowerPoint、および Word
Outlook

現在のラベルが適用されている場合は、それを取得するには、ファイルの秘密度ラベルオブジェクトで 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, and load its ID and name.
    const currentLabel = documentLabel.getCurrentOrNullObject();
    currentLabel.load("id,name");
    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})`);
    }
});

作成モードでメッセージまたは予定に現在適用されている秘密度ラベルを取得するには、次の例に示すように item.sensitivityLabel.getAsync を呼び出します。これにより、秘密度ラベルの GUID が返されます。

// Check the sensitivity label catalog status before calling other label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Get the current sensitivity label of a message or appointment.
        Office.context.mailbox.item.sensitivityLabel.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                console.log(asyncResult.value);
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

秘密度ラベルを設定します

Excel、PowerPoint、および Word
Outlook

ラベルを適用する前に、getLabels() (Excel、PowerPoint、Word) を呼び出し、返されたコレクションから有効なラベルまたはサブラベルを選択します。 tryToUpdate() メソッド (Excel、PowerPoint、Word) では、選択したラベルの ID をパラメーターとして必要とします。最初に getLabels() を呼び出すと、この必須 ID を取得し、現在のユーザーがラベルを使用できることを確認できます。返されたSensitivityLabelUpdateResult値 (Excel、PowerPoint、Word) を確認して、更新が成功したかどうかを判断します。

注:

サブラベルを持つ親ラベルを直接適用することはできません。有効になっているサブラベルの 1 つを代わりに選択します。

async function setDocumentSensitivityLabel(labelId: string) {
    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);
        await context.sync();

        // Check whether the label update succeeded.
        if (updateResult.value === Word.SensitivityLabelUpdateResult.success) {
            console.log("Applied the sensitivity label to the document.");
        } else {
            console.error(`The sensitivity label wasn't applied. Result: ${updateResult.value}`);
        }
    });
}

Outlook では、作成モードでメッセージまたは予定に 1 つの秘密度ラベルがサポートされています。ラベルを設定する前に、 context.sensitivityLabelsCatalog.getAsync を呼び出してラベルが使用可能であることを確認し、その GUID を取得します。次に、次の例に示すように、GUID を item.sensitivityLabel.setAsync に渡します。

// Check the sensitivity label catalog status before calling other label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Identify available sensitivity labels in the catalog.
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                if (catalog.length > 0) {
                    // Get the GUID of the sensitivity label.
                    var id = catalog[0].id;
                    // Set the mail item's sensitivity label using the label's GUID.
                    Office.context.mailbox.item.sensitivityLabel.setAsync(id, (asyncResult) => {
                        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                            console.log(asyncResult.status);
                        } else {
                            console.log("Action failed with error: " + asyncResult.error.message);
                        }
                    });
                } else {
                    console.log("Catalog list is empty");
                }
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

または、次の例に示すように、カタログ呼び出しによって返される SensitivityLabelDetails オブジェクトを渡します。

// Check the sensitivity label catalog status before calling other label methods.
Office.context.sensitivityLabelsCatalog.getIsEnabledAsync((asyncResult) => {
    if (asyncResult.status === Office.AsyncResultStatus.Succeeded && asyncResult.value == true) {
        // Identify available sensitivity labels in the catalog.
        Office.context.sensitivityLabelsCatalog.getAsync((asyncResult) => {
            if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                const catalog = asyncResult.value;
                if (catalog.length > 0) {
                    // Set the mail item's sensitivity label using the SensitivityLabelDetails object.
                    Office.context.mailbox.item.sensitivityLabel.setAsync(catalog[0], (asyncResult) => {
                        if (asyncResult.status === Office.AsyncResultStatus.Succeeded) {
                            console.log(asyncResult.status);
                        } else {
                            console.log("Action failed with error: " + asyncResult.error.message);
                        }
                    });
                } else {
                    console.log("Catalog list is empty");
                }
            } else {
                console.log("Action failed with error: " + asyncResult.error.message);
            }
        });
    } else {
        console.log("Action failed with error: " + asyncResult.error.message);
    }
});

OnSensitivityLabelChanged イベントを使用して秘密度ラベルの変更を検出する

注:

OnSensitivityLabelChanged イベントは Outlook でのみ使用できます。

OnSensitivityLabelChanged イベントを使用して、メッセージまたは予定の秘密度ラベルが変更されたときにアドインロジックを実行します。たとえば、特定の添付ファイルを含むメールアイテムのラベルをユーザーがダウングレードできないようにします。

OnSensitivityLabelChanged イベントは、イベントベースのアクティブ化を使用します。構成、デバッグ、および展開のガイダンスについては、「イベントを使用してアドインをアクティブ化する」を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-25