リンクされたエンティティ セル値は、外部データ ソースからのデータ型を統合し、通常のエンティティ値のようにエンティティ カードとしてデータを表示できます。 この機能を使用すると、すべてのデータをブックにダウンロードすることなく、大規模なデータ セットを表すデータ型をスケーリングできます。 Excel UI で使用できる 株式と地域のデータ ドメインには、 リンクされたエンティティ セル値が用意されています。 この記事では、Excel アドインで独自のデータ プロバイダーを作成して、エンド ユーザーにカスタム値を提供する方法について説明します。
リンクされたエンティティ セルの値は、外部データ ソースにリンクされます。 これらは、通常のエンティティ値よりも次の利点を提供します。
- リンクされたエンティティ セルの値は入れ子にすることができ、入れ子になったリンクされたエンティティ セルの値は参照されるまで取得されません。ユーザーまたはワークシートのいずれか。 これにより、ファイル サイズを減らし、ブックのパフォーマンスを向上させることができます。
- Excel では、キャッシュを使用して、異なるセルが同じリンクされたエンティティ セル値をシームレスに参照できるようにします。 これにより、ブックのパフォーマンスも向上します。
この記事では、次の記事で説明する情報について説明します。 独自のリンクされたエンティティ セル値を構築する方法を学習する前に、次の記事を読むことをお勧めします。
主な概念
リンクされたエンティティ セル値は、外部データ ソースからリンクされたデータをユーザーに提供します。 ユーザーは、カードエンティティ値として表示できます。
通常のエンティティ値と同様に、リンクされたエンティティ セル値は数式で参照できます。
定義
次の定義は、独自のリンクされたエンティティ セル値を実装する方法を理解するための基本的な定義です。
- リンクエンティティデータドメイン – リンクエンティティデータドメインは、エンティティが属する全体的なカテゴリを記述します。 たとえば、従業員、組織、自動車などがあります。
- リンクされたエンティティ セル値 – データ ドメインから作成されたインスタンス。 たとえば、Joe という名前のユーザーの従業員の値です。 カードエンティティ値として表示できます。
- データ プロバイダー - データ プロバイダーは、1 つ以上の登録済みリンク エンティティ データ ドメインのデータ ソースとして Excel によって認識されます。
- リンクされたエンティティ読み込みサービス関数 – リンクされているすべてのエンティティ データ ドメインは、そのドメインのデータ ソースとして機能するロード サービス関数を定義します。 リンクされたエンティティ読み込みサービス関数は、ブックのリンクされたエンティティ セル値を取得するための Excel からの要求を処理します。 これを TypeScript または JavaScript カスタム関数として実装します。
アドインがリンクされたエンティティ セル値を提供する方法
次の図は、アドインが読み込まれた後、新しいリンクされたエンティティ セル値をセルに挿入するときに発生する手順を示しています。 次の説明では、プロセスの各ステップでの動作について説明します。
- Excel はアドインを読み込み、アドインがサポートするすべてのリンクされたエンティティ データ ドメインを登録します。 各登録には、リンクされたエンティティ ロード サービス関数の ID が含まれます。 この ID は、後で Excel によって呼び出され、リンク エンティティ データ ドメインからリンクされたエンティティ セル値のプロパティ値を要求します。 この例では、 Products という名前の 1 つのデータ ドメインが登録されています。
- Excel は、リンク されたエンティティ データ ドメイン コレクション内の登録済みの各リンク エンティティ データ ドメインを追跡します。 これにより、Excel は、リンクされたエンティティ セル値にデータが必要な場合に、リンクされたエンティティ読み込みサービス関数を呼び出します。
- アドインは、新しいリンクされたエンティティ セル値をワークシートに挿入します。 この例では、製品 Chai に対して新しいリンクされたエンティティ セル値が作成されます。 これは通常、ユーザーがアドインのボタンを選択すると、1 つ以上のリンクされたエンティティ セル値が作成されます。 新しいリンクされたエンティティ セル値を作成すると、セルに表示される初期テキスト文字列のみが含まれます。 Excel は、リンクされたエンティティ読み込みサービス関数を呼び出して、残りのプロパティ値を取得します。 アドインは、カスタム関数からリンクされたエンティティ セル値を作成することもできます。
- Excel は、手順 1 で登録したリンクされたエンティティ読み込みサービス関数を呼び出します。 これは、新しいリンクされたエンティティ セル値を作成するたびに、またはデータ更新が行われる場合に発生します。 Excel では、リンクされたエンティティ読み込みサービス関数を呼び出して、すべてのプロパティ値を取得します。
- リンクされたエンティティ読み込みサービス関数は、Excel によって要求されたリンクエンティティ ID (Excel.LinkedEntityId) の最新のリンクされたエンティティ セル値 (Excel.LinkedEntityCellValue) を返します。 通常、リンクされたエンティティ読み込みサービス関数は、外部データ ソースに対してクエリを実行して値を取得し、リンクされたエンティティ セル値を作成します。 この例では、 製品 ID、 カテゴリ、 数量、 および価格 の値が返されます。
注:
Excel で複数のリンクされたエンティティ セル値が必要な場合、リンクされたエンティティ ID は、リンクされたエンティティ読み込みサービス関数にバッチとして渡されます。 その後、リンクされたエンティティ読み込みサービスは、すべての値のバッチ結果を返します。
以降のセクションでは、この記事で前に定義した用語の詳細について説明します。
データ プロバイダー
アドインはデータ プロバイダーであり、1 つ以上の登録済みデータ ドメインのデータ ソースとして Excel によって認識されます。 アドインは、リンクされたエンティティ セル値のデータを返す 1 つ以上のデータ プロバイダー関数を公開します。 データ プロバイダーは、Contoso などのテキスト文字列またはアドインの名前によって識別されます。 名前はアドイン内で一意である必要があります。
リンクされたエンティティ データ ドメイン
データ プロバイダー (アドイン) は、1 つ以上のデータ ドメインを登録します。 データ ドメインは、エンティティを Excel に記述します。 たとえば、データ プロバイダーは 、製品 と カテゴリ のデータ ドメインを提供できます。 ドメインを Excel に登録して、これらのドメインと連携してリンクされたエンティティ セル値を取得および表示し、計算を実行できるようにする必要があります。
データ ドメインは、次の属性を Excel に記述します。
- 関連付けられているデータ プロバイダーの名前。
- 製品など、一意に識別するドメイン ID。
- ユーザーの表示名 ( 製品など)。
- Excel でリンクされたエンティティ セル値が必要な場合に呼び出すリンクエンティティ読み込みサービス関数。
- 更新の頻度を示す、指定された更新モードと間隔。
リンクされたエンティティ データ ドメインの例として、都市のリンクされたエンティティ セル値を提供する Excel の Geography データ ドメインがあります。
リンクされたエンティティ セルの値
リンクされたエンティティ セル値は、データ ドメインから作成されたインスタンスです。 たとえば、 Geography データ ドメインの Seattle の値です。 通常のエンティティ セル値のようなエンティティ値カード表示されます。
リンクされたエンティティ セルの値はデータ ドメインにリンクされているため、更新できます。 また、入れ子になったリンクされたエンティティ セルの値は、ユーザーが要求しない限り取得されません (エンティティカードの表示など)。 また、入れ子になったエンティティ セルの値は、ワークシート (数式など) から参照されない限り、ワークシートに保存されません。 これにより、ファイル サイズが縮小され、パフォーマンスが向上します。
リンクされたエンティティロードサービス関数
各データ ドメインには、リンクされたエンティティ セル値が必要な場合に Excel が呼び出すことができる関数が必要です。 アドインは、 @linkedEntityLoadServiceでタグ付けされた JavaScript または TypeScript 関数としてサービスを提供します。 最適なパフォーマンスを得るには、1 つのロード サービス関数のみを作成することをお勧めします。 Excel は、リンクされたエンティティ セル値に対するすべての要求をバッチとしてロード サービス関数に送信します。
データ ドメインを使用してデータ プロバイダーを作成する
この記事の次のセクションでは、 Contoso のデータ プロバイダーである Excel アドインを実装するために TypeScript コードを記述する方法について説明します。 製品とカテゴリという名前の 2 つのデータ ドメインが提供されます。
データ ドメインを登録する
製品とカテゴリという名前の新しいドメインを登録するコードを見てみましょう。 データ プロバイダー名は Contoso です。 アドインが読み込まれると、最初にデータ ドメインが Excel に登録されます。
Excel.LinkedEntityDataDomainCreateOptions 型を使用して、リンクされたエンティティ読み込みサービスとして使用する関数など、必要なオプションを記述します。 次に、 Workbook.linkedEntityDataDomains コレクションにドメインを追加します。 Office アドインを初期化するときは、ドメインを登録することをお勧めします。 次のコードは、 製品、 カテゴリ、 サプライヤー のデータ ドメインを登録する方法を示しています。
Office.onReady(async () => {
await Excel.run(async (context) => {
const productsDomain: Excel.LinkedEntityDataDomainCreateOptions = {
dataProvider: "Contoso",
id: "products",
name: "Products",
// ID of the custom function that is called on demand by Excel to resolve or refresh linked entity cell values of this data domain.
loadFunctionId: "CONTOSOLOADSERVICE",
// periodicRefreshInterval is only required when supportedRefreshModes contains "Periodic".
periodicRefreshInterval: 300,
// Manual refresh mode is always supported, even if unspecified.
supportedRefreshModes: [
Excel.LinkedEntityDataDomainRefreshMode.periodic,
Excel.LinkedEntityDataDomainRefreshMode.onLoad
]
};
const categoriesDomain: Excel.LinkedEntityDataDomainCreateOptions = {
dataProvider: "Contoso",
id: "categories",
name: "Categories",
loadFunctionId: "CONTOSOLOADSERVICE",
periodicRefreshInterval: 300,
supportedRefreshModes: [
Excel.LinkedEntityDataDomainRefreshMode.periodic,
Excel.LinkedEntityDataDomainRefreshMode.onLoad
]
};
const suppliersDomain: Excel.LinkedEntityDataDomainCreateOptions = {
dataProvider: "Contoso",
id: "suppliers",
name: "Suppliers",
loadFunctionId: "CONTOSOLOADSERVICE"
};
// Register the data domains by adding them to the collection.
context.workbook.linkedEntityDataDomains.add(productsDomain);
context.workbook.linkedEntityDataDomains.add(categoriesDomain);
context.workbook.linkedEntityDataDomains.add(suppliersDomain);
await context.sync();
});
});
リンクされたエンティティ セル値を挿入する
リンクされたエンティティ セル値をワークシートのセルに挿入するには、2 つの方法があります。
- リボンにコマンド ボタンを作成するか、作業ウィンドウのボタンを作成します。 ユーザーがボタンを選択すると、コードによってリンクされたエンティティ セル値が挿入されます。
- リンクされたエンティティ セル値を返すカスタム関数を作成します。
次のコード例は、新しいリンクされたエンティティ セル値を選択したセルに挿入する方法を示しています。 このコードは、リボンのコマンド ボタンまたは作業ウィンドウのボタンから呼び出すことができます。 次のコードに関する注意事項:
- 返すリンクされたエンティティ セル値には、
268436224のserviceIdを指定する必要があります。 これにより、リンクされたエンティティ セルの値が Excel アドインに関連付けられていることが Excel に通知されます。 -
cultureを指定する必要があります。 Excel は、ブックが別のカルチャで開かれたときに元のカルチャを維持できるように、リンクされたエンティティ読み込みサービス関数に渡します。 -
textプロパティは、リンクされたエンティティ データ値が更新されている間、セル内のユーザーに表示されます。 これにより、更新が完了している間にユーザーに空白のセルが表示されるのを防ぎます。
async function insertProduct() {
await Excel.run(async (context) => {
const productLinkedEntity: Excel.LinkedEntityCellValue = {
type: Excel.CellValueType.linkedEntity,
id: {
entityId: "P1", // Don't use exclamation marks in this value.
domainId: "products", // Don't use exclamation marks in this value.
serviceId: 268436224,
culture: "en-US",
},
text: "Chai",
};
context.workbook.getActiveCell().valuesAsJson = [[productLinkedEntity]];
await context.sync();
});
}
注:
entityIDまたはdomainId値に感嘆符を使用しないでください。
次のコード サンプルは、カスタム関数を使用してリンクされたエンティティ セル値を挿入する方法を示しています。 ユーザーは、任意のセルに =CONTOSO.GETPRODUCTBYID("productid") を入力することで、リンクされたエンティティ セルの値を取得できます。 前のコード サンプルのメモもこのコード サンプルに適用されます。
/**
* Custom function that shows how to insert a `LinkedEntityCellValue`.
* @customfunction
* @param {string} productID Unique ID of the product.
* @return {any} `LinkedEntityCellValue` for the requested product, if found.
*/
function getProductById(productID: string): any {
const product = getProduct(productID);
if (product === null) {
throw new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable, "Invalid productID");
}
const productLinkedEntity: Excel.LinkedEntityCellValue = {
type: Excel.CellValueType.linkedEntity,
id: {
entityId: product.productID,
domainId: "products",
serviceId: 268436224,
culture: "en-US",
},
text: product.productName
};
return productLinkedEntity;
}
リンクされたエンティティ読み込みサービス関数を実装する
アドインは、リンクされたエンティティ のセル値にプロパティ値が必要な場合に、Excel からの要求を処理するためのリンクされたエンティティ読み込みサービス関数を提供する必要があります。 関数は、 @linkedEntityLoadService JSDoc タグで識別されます。
次のコード例は、 Excel からの Products および Categories データ ドメインに対するデータ要求を処理する関数を作成する方法を示しています。 次のコードに関する注意事項:
- ヘルパー関数を使用して、リンクされたエンティティ セル値を作成します。 そのコードは後で示します。
- エラーが発生すると、
CustomFunctions.ErrorCode.notAvailableエラーがスローされます。 これにより、ユーザーに表示されるセルに#CONNECT!が表示されます。
// Linked entity data domain constants
const productsDomainId = "products";
const categoriesDomainId = "categories";
const suppliersDomainId = "suppliers";
// Linked entity cell value constants
const addinDomainServiceId = 268436224;
const defaultCulture = "en-US";
/**
* Custom function which acts as the "service" or the data provider for a `LinkedEntityDataDomain`, that is
* called on demand by Excel to resolve/refresh `LinkedEntityCellValue`s of that `LinkedEntityDataDomain`.
* @customfunction
* @linkedEntityLoadService
* @param {any} request Request to resolve/refresh `LinkedEntityCellValue` objects.
* @return {any} Resolved/Refreshed `LinkedEntityCellValue` objects that were requested in the passed-in request.
*/
function contosoLoadService(request: any): any {
const notAvailableError = new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable);
console.log(`Fetching linked entities from request: ${request} ...`);
try {
// Parse the request that was passed-in by Excel.
const parsedRequest: Excel.LinkedEntityLoadServiceRequest = JSON.parse(request);
// Initialize result to populate and return to Excel.
const result: Excel.LinkedEntityLoadServiceResult = { entities: [] };
// Identify the domainId of the request and call the corresponding function to create
// linked entity cell values for that linked entity data domain.
for (const { entityId } of parsedRequest.entities) {
var linkedEntityResult = null;
switch (parsedRequest.domainId) {
case productsDomainId: {
linkedEntityResult = makeProductLinkedEntity(entityId);
break;
}
case categoriesDomainId: {
linkedEntityResult = makeCategoryLinkedEntity(entityId);
break;
}
case suppliersDomainId: {
linkedEntityResult = makeSupplierLinkedEntity(entityId);
break;
}
default:
throw notAvailableError;
}
if (!linkedEntityResult) {
// Throw an error to signify to Excel that resolution/refresh of the requested linkedEntityId failed.
throw notAvailableError;
}
result.entities.push(linkedEntityResult);
}
return result;
} catch (error) {
console.error(error);
throw notAvailableError;
}
}
次のコード サンプルは、製品のリンクされたエンティティ セル値を作成するヘルパー関数を示しています。 この関数は、特定の製品 ID のリンクされたエンティティを作成するために、前のコード contosoLoadService によって呼び出されます。 次のコードに関する注意事項:
-
type、id、およびtextプロパティには、前のinsertProductの例と同じ設定が使用されます。 - これには、
Product NameやUnit Priceなど、Products データ ドメインに固有の追加のプロパティが含まれます。 - 製品のカテゴリの遅延入れ子になったリンク エンティティが作成されます。 カテゴリのプロパティは、必要になるまで要求されません。
/** Helper function to create a linked entity from product properties. */
function makeProductLinkedEntity(productID: string): any {
// Search the product data in the data source for a matching product ID.
const product = getProduct(productID);
if (product === null) {
// Return null if no matching product is found.
return null;
}
const productLinkedEntity: Excel.LinkedEntityCellValue = {
type: "LinkedEntity",
text: product.productName,
id: {
entityId: product.productID,
domainId: productsDomainId,
serviceId: addinDomainServiceId,
culture: defaultCulture
},
properties: {
"Product ID": {
type: "String",
basicValue: product.productID
},
"Product Name": {
type: "String",
basicValue: product.productName
},
"Quantity Per Unit": {
type: "String",
basicValue: product.quantityPerUnit
},
// Add Unit Price as a formatted number.
"Unit Price": {
type: "FormattedNumber",
basicValue: product.unitPrice,
numberFormat: "$* #,##0.00"
},
Discontinued: {
type: "Boolean",
basicValue: product.discontinued
}
},
layouts: {
compact: {
icon: "ShoppingBag"
},
card: {
title: { property: "Product Name" },
sections: [
{
layout: "List",
properties: ["Product ID"]
},
{
layout: "List",
title: "Quantity and price",
collapsible: true,
collapsed: false,
properties: ["Quantity Per Unit", "Unit Price"]
},
{
layout: "List",
title: "Additional information",
collapsed: true,
properties: ["Discontinued"]
}
]
}
}
};
// Add image property to the linked entity and then add it to the card layout.
if (product.productImage) {
productLinkedEntity.properties["Image"] = {
type: "WebImage",
address: product.productImage
};
productLinkedEntity.layouts.card.mainImage = { property: "Image" };
}
// Add a deferred nested linked entity for the product category.
const category = getCategory(product.categoryID.toString());
if (category) {
productLinkedEntity.properties["Category"] = {
type: "LinkedEntity",
text: category.categoryName,
id: {
entityId: category.categoryID.toString(),
domainId: categoriesDomainId,
serviceId: addinDomainServiceId,
culture: defaultCulture
}
};
// Add nested product category to the card layout.
productLinkedEntity.layouts.card.sections[0].properties.push("Category");
}
// Add a deferred nested linked entity for the supplier.
const supplier = getSupplier(product.supplierID.toString());
if (supplier) {
productLinkedEntity.properties["Supplier"] = {
type: "LinkedEntity",
text: supplier.companyName,
id: {
entityId: supplier.supplierID.toString(),
domainId: suppliersDomainId,
serviceId: addinDomainServiceId,
culture: defaultCulture
}
};
// Add nested product supplier to the card layout.
productLinkedEntity.layouts.card.sections[2].properties.push("Supplier");
}
return productLinkedEntity;
}
次のコード サンプルは、カテゴリのリンクされたエンティティ セル値を作成するヘルパー関数を示しています。 この関数は、前のコード contosoLoadService によって呼び出され、特定のカテゴリ ID のリンクされたエンティティを作成します。
/** Helper function to create a linked entity from category properties. */
function makeCategoryLinkedEntity(categoryID: string): any {
// Search the sample JSON category data for a matching category ID.
const category = getCategory(categoryID);
if (category === null) {
// Return null if no matching category is found.
return null;
}
const categoryLinkedEntity: Excel.LinkedEntityCellValue = {
type: "LinkedEntity",
text: category.categoryName,
id: {
entityId: category.categoryID,
domainId: categoriesDomainId,
serviceId: addinDomainServiceId,
culture: defaultCulture
},
properties: {
"Category ID": {
type: "String",
basicValue: category.categoryID,
propertyMetadata: {
// Exclude the category ID property from the card view and auto-complete.
excludeFrom: {
cardView: true,
autoComplete: true
}
}
},
"Category Name": {
type: "String",
basicValue: category.categoryName
},
Description: {
type: "String",
basicValue: category.description
}
},
layouts: {
compact: {
icon: "Branch"
}
}
};
return categoryLinkedEntity;
}
次のコード サンプルは、サプライヤーのリンクされたエンティティ セル値を作成するヘルパー関数を示しています。 この関数は、前のコード contosoLoadService によって呼び出され、特定のサプライヤー ID のリンクされたエンティティを作成します。
/** Helper function to create linked entity from supplier properties. */
function makeSupplierLinkedEntity(supplierID: string): any {
// Search the sample JSON category data for a matching supplier ID.
const supplier = getSupplier(supplierID);
if (supplier === null) {
// Return null if no matching supplier is found.
return null;
}
const supplierLinkedEntity: Excel.LinkedEntityCellValue = {
type: "LinkedEntity",
text: supplier.companyName,
id: {
entityId: supplier.supplierID,
domainId: suppliersDomainId,
serviceId: addinDomainServiceId,
culture: defaultCulture
},
properties: {
"Supplier ID": {
type: "String",
basicValue: supplier.supplierID
},
"Company Name": {
type: "String",
basicValue: supplier.companyName
},
"Contact Name": {
type: "String",
basicValue: supplier.contactName
},
"Contact Title": {
type: "String",
basicValue: supplier.contactTitle
}
},
cardLayout: {
title: { property: "Company Name" },
sections: [
{
layout: "List",
properties: ["Supplier ID", "Company Name", "Contact Name", "Contact Title"]
}
]
}
};
return supplierLinkedEntity;
}
次のコード サンプルには、前のコード サンプルで使用できるサンプル データが含まれています。
/// Sample product data.
const products = [
{
productID: "P1",
productName: "Chai",
supplierID: "S1",
categoryID: "C1",
quantityPerUnit: "10 boxes x 20 bags",
unitPrice: 18,
discontinued: false,
productImage: "https://upload.wikimedia.org/wikipedia/commons/thumb/0/04/Masala_Chai.JPG/320px-Masala_Chai.JPG"
}
];
/// Sample product category data.
const categories = [
{
categoryID: "C1",
categoryName: "Beverages",
description: "Soft drinks, coffees, teas, beers, and ales"
}];
/// Sample product supplier data.
const suppliers = [
{
supplierID: "S1",
companyName: "Exotic Liquids",
contactName: "Ema Vargova",
contactTitle: "Purchasing Manager"
}];
データ更新オプション
データ ドメインを登録すると、[データ] タブから [すべて更新] を選択するなどして、ユーザーはいつでも手動で更新できます。データ ドメインに対して指定できる更新モードは 3 つあります。
-
manual- データは、ユーザーが更新を選択した場合にのみ更新されます。 既定のモード。 手動更新は、更新モードがonLoadまたはperiodicに設定されている場合でも、ユーザーが常に実行できます。 -
onLoad- データ ドメインが登録されると (通常はアドインが読み込まれるときに) データが更新されます。 その後、データはユーザーによって手動でのみ更新されます。 ブックを開いたときにデータを更新する場合は、ドキュメントを開くときに読み込むようにアドインを構成します。 詳細については、「 ドキュメントが開いたときに Office アドインでコードを実行する」を参照してください。 -
periodic- データ ドメインが登録されると (通常はアドインが読み込まれるときに) データが更新されます。 その後、指定した時間間隔の後にデータが継続的に更新されます。 たとえば、データ ドメインが 300 秒ごとに更新されることを指定できます (最小値)。 更新間隔は分単位でのみ実行されるため、秒数は常に最も近い分数に切り上げられます。
次のコード例は、読み込み時に更新するようにデータ ドメインを構成し、5 分ごとに更新を続行する方法を示しています。
const productsDomain: Excel.LinkedEntityDataDomainCreateOptions = {
dataProvider: domainDataProvider,
id: "products",
name: "Products",
// ID of the custom function that is called on demand by Excel to resolve or refresh linked entity cell values of this data domain.
loadFunctionId: loadFunctionId,
// periodicRefreshInterval is only required when supportedRefreshModes contains "Periodic".
periodicRefreshInterval: 300, // equivalent to 5 minutes.
// Manual refresh mode is always supported, even if unspecified.
supportedRefreshModes: [
Excel.LinkedEntityDataDomainRefreshMode.periodic,
Excel.LinkedEntityDataDomainRefreshMode.onLoad
]
};
次のいずれかの方法を使用して、リンクされたエンティティ データ ドメインに対してプログラムで更新を要求することもできます。
-
LinkedEntityDataDomain.refresh()- リンクされたエンティティ データ ドメインのすべてのLinkedEntityCellValueオブジェクトを更新します。 -
LinkedEntityDataDomainCollection.refreshAll()- コレクション内のすべてのリンクされたエンティティ データ ドメインのすべてのLinkedEntityCellValueオブジェクトを更新します。
refresh メソッドは、非同期的に行われる更新を要求します。 更新の結果を確認するには、 onRefreshCompleted イベントをリッスンします。 次のコード サンプルは、 onRefreshCompleted イベントをリッスンする例を示しています。
await Excel.run(async (context) => {
const dataDomains = context.workbook.linkedEntityDataDomains;
dataDomains.onRefreshCompleted.add(onLinkedEntityDomainRefreshed);
await context.sync();
});
async function onLinkedEntityDomainRefreshed(eventArgs: Excel.LinkedEntityDataDomainRefreshCompletedEventArgs): Promise<any> {
console.log("Linked entity domain refreshed: " + eventArgs.id);
console.log("Refresh status: " + eventArgs.refreshed);
console.log("Refresh error: " + eventArgs.errors);
return null;
}
リンクされたエンティティ読み込みサービスでのエラー処理
Excel がアドインを呼び出してリンクされたエンティティ セル値のデータを取得すると、エラーが発生する可能性があります。 アドインが読み込まれていない場合など、Excel がアドインにまったく接続できない場合は、ユーザーに #CONNECT! エラーが表示されます。
リンクされたエンティティ読み込みサービス関数でエラーが発生した場合は、 notAvailableError エラーがスローされます。 これにより、Excel はユーザーに #CONNECT! を表示します。
次のコードは、リンクされたエンティティ読み込みサービス関数でエラーを処理する方法を示しています。
async function contosoLoadService(request: any): Promise<any> {
const notAvailableError = new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable);
try {
// Create and return a new linked entity cell value.
let linkedEntityResult = ...
...
if (!linkedEntityResult) {
// Throw an error to signify to Excel that resolution or refresh of the requested linkedEntityId failed.
throw notAvailableError;
}
...
} catch (error) {
console.error(error);
throw notAvailableError;
}
}
リンクされたエンティティ読み込みサービスのデバッグ
リンクされたエンティティ データ型のほとんどのアドイン機能は、「 Office アドインのデバッグの概要」のガイダンスを使用してデバッグできます。ただし、リンクされたエンティティ読み込みサービス関数は、共有ランタイムまたは JavaScript 専用ランタイム (カスタム関数ランタイムとも呼ばれます) に実装できます。JavaScript 専用ランタイムで関数を実装する場合は、 非共有ランタイム ガイダンスでカスタム関数デバッグを 使用します。
リンクされたエンティティ読み込みサービス関数は、使用するランタイムに関係なく、カスタム関数アーキテクチャを使用します。 ただし、通常のカスタム関数とは大きな違いがあります。
リンクされたエンティティ読み込みサービス関数には、カスタム関数とは次の違いがあります。
- 数式で使用するためにエンド ユーザーには表示されません。
- JSDoc タグの
@streamingや@volatileはサポートされていません。 これらのタグが使用されている場合、ユーザーに #CALC! エラーが表示されます。
リンクされたエンティティ読み込みサービス関数には、カスタム関数と次の類似点があります。
- カスタム関数の名前付けとローカライズを使用します。
- 同じエラー処理方法を使用します。
Excel 2019 以前の動作
リンクされたエンティティ セル値をサポートしていない古いバージョンの Excel で、リンクされたエンティティ セル値を含むワークシートを開いた場合、Excel はセル値をエラーとして表示します。 これが設計された動作です。 これは、リンクされたエンティティ セル値を挿入または更新するたびに、 basicType を Error に設定し、 basicValue を #VALUE! するように設定する理由でもあります。 これは、Excel が古いバージョンのフォールバックとして使用するエラーです。
ベスト プラクティス
-
entityIDまたはdomainId値に感嘆符を使用しないでください。 - リンクされたエンティティ データ ドメインを初期化コード
Office.OnReadyに登録して、リンクされたエンティティ セルの値を更新する機能などの即時機能をユーザーに付与します。 - アドインを発行した後は、リンクされたエンティティ データ ドメイン ID を変更しないでください。 同じ論理オブジェクト間で一貫性のある ID を使用すると、パフォーマンスが向上します。
- 新しいリンクされたエンティティ セル値を作成するときは、常に
textプロパティを指定します。 この値は、Excel がデータ プロバイダー関数を呼び出して残りのプロパティ値を取得している間に表示されます。 それ以外の場合、データが取得されるまで空白のセルが表示されます。
関連項目
GitHub で Microsoft と共同作業する
このコンテンツのソースは GitHub にあります。そこで、issue や pull request を作成および確認することもできます。 詳細については、共同作成者ガイドを参照してください。
Office Add-ins