カスタムデータの追加

KML では、3 つの方法で KML Feature にカスタムデータに追加できます。どの方法を選択するかは、追加するデータの種類や、KML プレゼンテーションでのデータの使用方法により異なります。具体的には、<ExtendedData> の以下の要素またはデータを使用してカスタムデータを追加します:

<Data> 要素 - 特定の Feature（NetworkLink、Placemark、GroundOverlay、PhotoOverlay、ScreenOverlay、Document、または Folder）に関連付けられたユーザーデータに、型なしの名前/値ペアを追加できます。デフォルトでは、これらの名前/値ペアがバルーンに表示されます。この情報は、<BalloonStyle> の <text> 要素内でのエンティティ置換にも使用できます（BalloonStyle 要素をテンプレートとして使用するをご覧ください）。
<Schema> および <SchemaData> 要素 - 特定の Feature が関連付けられたユーザーデータに、型付きデータを追加できます。
任意の XML データ - KML ファイル内にユーザーデータを保存できます。Google Earth では、このデータがファイルと一緒に渡されて保存されますが、使用されることはありません。

注: これら 3 つの方法を、同じファイル内で混在させても構いません。各種データを別々のソースに追加する場合は、一部のカスタムデータには型付きデータ（Schema/SchemaData）を使用し、その他のカスタムデータには型なしデータ（Data）を使用することもできます。

どの方法を使用すべきか

KML Feature に「型なし」データを追加する方法としては、ほとんどの場合 <Data> 要素が最も単純で効果的です。この方法は比較的簡単に実施でき、KML ファイル内のすべての Placemark に適用できる BalloonStyle テンプレートを使用しやすいという利点があります（この使用方法の例については、拡張データ要素のエンティティ置換をご覧ください）。

<Schema> および <SchemaData> 要素を使用すると、「型付き」ユーザーデータを追加できます。これらは、地理情報システム（GIS）データを使用しているユーザー向けに提供されている要素です。外部のコンピュータアプリケーションで使用している型付きデータがある場合は、<Schema> 要素と <SchemaData> 要素を使用して、構造化されたデータ型を Feature に追加する必要があります（Google Earth ではこの型付き情報は使用しませんが、他のアプリケーションで必要になる場合があります）。このような利用を考えていない場合は、この方法の技術的な側面についてこれ以上詳しく理解する必要はないかもしれません。<Data> と同じように、<SchemaData> を使うと BalloonStyle のテンプレートが利用しやすくなります。

単純にデータを KML ファイルとともに渡すだけでよく、Google Earth でデータを処理する必要がない場合は、任意の XML データ機能を使用してください。XML 名前空間の接頭辞を参照して、現在の KML コンテキスト内のデータとともに渡すことができます。詳細については、任意の XML データをご覧ください。

型なし名前/値ペアの追加

KML Feature に型なしの名前/値ペアを追加する方法としては、<Data> 要素が最も単純で効果的です。この要素の構文は次のとおりです:

<ExtendedData>                       
 <Data name="string">
  <displayName>...</displayName>    <!-- string -->
    <value>...</value>                <!-- string -->
 </Data> </ExtendedData>

name 属性は、このデータを一意に識別するための ID です。<displayName> 要素は、このデータ名をわかりやすい形式で表示する場合に使用します。<displayName> には、スペース、URL、ハイパーリンクを含む CDATA を格納できます。

次に、ゴルフコース内のいくつかのホールに、カスタムデータを含む Placemark を追加した例を示します:

<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>My Golf Course Example</name>
  <Placemark>
    <name>Club house</name>
    <ExtendedData>
      <Data name="holeNumber">
        <value>1</value>
      </Data>
      <Data name="holeYardage">
        <value>234</value>
      </Data>
      <Data name="holePar">
        <value>4</value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-111.956,33.5043</coordinates>
    </Point>
 </Placemark> <Placemark> <name>By the lake</name> <ExtendedData> <Data name="holeNumber"> <value>5</value> </Data> <Data name="holeYardage"> <value>523</value> </Data> <Data name="holePar"> <value>5</value> </Data> </ExtendedData> <Point> <coordinates>-111.95,33.5024</coordinates> </Point>
 </Placemark> </Document> </kml>

この画面キャプチャは、Placemark バルーン内のテーブルに、<Data> 要素がデフォルトの状態でどのように表示されるかを示しています:

バルーンのデフォルトのスタイルを使用した Data の例

レビュー: BalloonStyle 要素をテンプレートとして使用する

KML では、定義したスタイルに ID を割り当てることができます。この方法で定義したスタイルは、KML ファイル内（他の KML ファイルでも構いません）から、<styleUrl> 要素を使用して繰り返し参照できます。この方法で定義したスタイルを、「共有スタイル」といいます。<BalloonStyle> 内の <text> 要素では、「エンティティ置換」がサポートされています。個々の値を、エンティティのインスタンスごとに置き換えることができます。置換が可能な標準エンティティは次のとおりです:

$[name]: Placemark の name で置き換えられます。
$[description]: Placemark の description で置き換えられます。
$[address]: Placemark の address で置き換えられます。
$[id]: Placemark の ID で置き換えられます。
$[Snippet]: Placemark の Snippet で置き換えられます。
$[geDirections]: Placemark の運転ルート（To/From）で置き換えられます。

拡張データ要素のエンティティ置換

Google Earth では、<BalloonStyle> の <text> に含まれる特定の拡張データ要素のエンティティ置換もサポートされます。以下のエンティティを <text> 要素内で参照できます:

変数	置換に使用する要素	例
$[name_attribute_of_Data_element]	<value> 要素の内容	holeNumber、holeYardage
$[name_attribute_of_Data/displayName]	<displayName> 要素の内容	ホールの番号、ホールのヤード数

次に、ゴルフコース用の <BalloonStyle> テンプレートの作成例を示します。この例では、Placemark バルーンごとに Placemark 名を置き換え、各ホールのホール番号、パー、ヤード数などの情報を書き出しています。

<?xml version="1.0" encoding="UTF-8"?><kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>Data+BalloonStyle</name>
  <Style id="golf-balloon-style">
    <BalloonStyle>
      <text>
        <![CDATA[
          This is $[name]
          This is hole $[holeNumber]
          The par for this hole is $[holePar]
          The yardage is $[holeYardage]
        ]]>
      </text>
    </BalloonStyle>
  </Style>
  <!-- Shared style sample
        Two Placemarks use the same balloon template
  -->
  <Placemark>
    <name>Club house</name>
    <styleUrl>#golf-balloon-style</styleUrl>
    <ExtendedData>
      <Data name="holeNumber">
        <value>1</value>
      </Data>
      <Data name="holeYardage">
        <value>234</value>
      </Data>
      <Data name="holePar">
        <value>4</value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-111.956,33.5043</coordinates>
    </Point>
  </Placemark>
  <Placemark>
    <name>By the lake</name>
    <styleUrl>#golf-balloon-style</styleUrl>
    <ExtendedData>
      <Data name="holeNumber">
        <value>5</value>
      </Data>
      <Data name="holeYardage">
        <value>523</value>
      </Data>
      <Data name="holePar">
        <value>5</value>
      </Data>
    </ExtendedData>
    <Point>
      <coordinates>-111.95,33.5024</coordinates>
    </Point>
  </Placemark>
</Document>
</kml>

次にこの例の画面キャプチャを示します:

バルーンのデフォルトのスタイルを使用した Data の例

次に、<displayName> 要素を使用したより実践的な例を示します。この手法は、テキストをローカライズする場合や、複雑な書式を設定したい場合に適しています。

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2">
 <Document>
 <name>Entity-Replacement</name>
 <Style id="displayName-value">
 <BalloonStyle>
 <text>
 <![CDATA[
 This is $[name]<br/>
 $[holeNumber/displayName] $[holeNumber]<br/>
 $[holePar/displayName] $[holePar]<br/>
 $[holeYardage/displayName] $[holeYardage]
 ]]>
 </text>
 </BalloonStyle>
 </Style>
 <!-- Shared style sample
 Two Placemarks use the same balloon template
 -->
 <Placemark>
 <name>Club house</name>
 <styleUrl>#displayName-value</styleUrl>
 <ExtendedData>
 <Data name="holeNumber">
 <displayName><![CDATA[
 <b>This is hole </b>
 ]]></displayName>
 <value>1</value>
 </Data>
 <Data name="holePar">
 <displayName><![CDATA[
 <i>The par for this hole is </i>
 ]]></displayName>
 <value>4</value>
 </Data>
 <Data name="holeYardage">
 <displayName><![CDATA[
 <b><i>The yardage is </i></b>
 ]]></displayName>
 <value>234</value>
 </Data>
 </ExtendedData>
 <Point>
 <coordinates>-111.956,33.5043</coordinates>
 </Point>
 </Placemark>
 <Placemark>
 <name>By the lake</name>
 <styleUrl>#Entity-Replacement</styleUrl>
 <ExtendedData>
 <Data name="holeNumber">
 <displayName><![CDATA[
 <b>This is hole </b>
 ]]></displayName>
 <value>5</value>
 </Data>
 <Data name="holePar">
 <displayName><![CDATA[
 <i>The par for this hole is </i>
 ]]></displayName>
 <value>5</value>
 </Data>
 <Data name="holeYardage">
 <displayName><![CDATA[
 <b><i>The yardage is </i></b>
 ]]></displayName>
 <value>523</value>
 </Data>
 </ExtendedData>
 <Point>
 <coordinates>-111.95,33.5024</coordinates>
 </Point>
 </Placemark>
 </Document>
</kml>

次に、このバルーンスタイルテンプレートを使用したバルーンの例を示します。

Feature への型付きデータの追加

<Schema> および <SchemaData> 要素を使用すると、Feature に型付きデータを追加できます。この機能は、型付きデータを扱う GIS およびプログラミングアプリケーションで必要になります。

型付きデータの追加の概要

KML Feature にカスタムデータを追加するには、次の 2 つの基本タスクを実行します:

新しい型を宣言する <Schema> 要素を作成します。
<SchemaData> 要素を使用して新しい型のインスタンスを作成します。

Schema 要素の宣言

Schema 要素は、新しい型を宣言するために使用します。<Schema> は常に <Document> の子要素となります。Document には 0 個以上の Schema 要素を含めることができます。

ID 属性

<Schema> 要素には、常に ID 属性が必要です。この ID 属性は、<SchemaData> でこの型のインスタンスを作成するときに参照されます。この ID は、KML ファイル内で一意である必要があります。

name 属性

name 属性は、エンティティ置換に使用するオプションの属性です。

構文

Schema 要素の構文は次のとおりです:

<Schema name="string" id="ID">   
  <SimpleField type="string" name="string">     
    <displayName>...</displayName>            <!-- string -->   
  </SimpleField> 
</Schema>

<SimpleField> には、常に name 属性と type 属性が必要です。両方の属性が揃っていないと、このフィールドは無視されます。name 属性は、<BalloonStyle> の <text> 要素のエンティティ置換にも使用されます。Simplefield 型には、次のいずれかを指定します:

string
int
uint
short
ushort
float
double
bool

データの各インスタンスの定義

ユーザーが定義した型のインスタンスを作成するには、<SchemaData> 要素を使用します。<SchemaData> の構文は次のとおりです:

<ExtendedData>                   
  <SchemaData schemaUrl="anyURI">
    <SimpleData name=""> ... </SimpleData>       <!-- string -->
  </SchemaData>
</ExtendedData>

schemaUrl 属性は、型を宣言する Schema の id を参照します（styleUrl が、既に宣言されている Style の id を参照するのと同じことです）。schemaUrl が http アドレスである場合は、ファイルがネットワークから取得されます。特定のユーザー定義型のインスタンスは、Placemark ごとに 1 つのみ作成できます。

例

次の例では、ScenicVista というユーザー定義型を宣言しています。この型には、TrailHeadName、TrailLength、Elevatio Gain という 3 つのフィールドがあります。TrailHeadName フィールドには、string 型の値を格納します。TrailLength フィールドには、double 型の値を格納します。ElevationGain フィールドには、int 型の値を格納します。Easy trail という Placemark に、このユーザー定義型のインスタンスを格納します。このインスタンスの TrailHeadName フィールドに「Pi in the sky」、TrailLength フィールドに「3.14159」、ElevationGain フィールドに「10」という値を設定します。

<kml xmlns="http://www.opengis.net/kml/2.2"> 
<Document>   
  <name>ExtendedData+SchemaData</name>   
  <open>1</open>

  <!-- Declare the type "TrailHeadType" with 3 fields -->
  <Schema name="TrailHeadType" id="TrailHeadTypeId">     
    <SimpleField type="string" name="TrailHeadName">       
      <displayName><![CDATA[<b>Trail Head Name</b>]]></displayName>     
    </SimpleField>     
    <SimpleField type="double" name="TrailLength">       
      <displayName><![CDATA[<i>Length in miles</i>]]></displayName>     
    </SimpleField>     
    <SimpleField type="int" name="ElevationGain">       
      <displayName><![CDATA[<i>Change in altitude</i>]]></displayName>     
    </SimpleField>   
  </Schema> 

<!-- This is analogous to adding three fields to a new element of type TrailHead:

  <TrailHeadType>        
    <TrailHeadName>...</TrailHeadName>        
    <TrailLength>...</TrailLength>        
    <ElevationGain>...</ElevationGain>    
 </TrailHeadType>
--> <!-- Instantiate some Placemarks extended with TrailHeadType fields --> <Placemark> <name>Easy trail</name> <ExtendedData> <SchemaData schemaUrl="#TrailHeadTypeId">  <SimpleData name="TrailHeadName">Pi in the sky</SimpleData> <SimpleData name="TrailLength">3.14159</SimpleData> <SimpleData name="ElevationGain">10</SimpleData> </SchemaData>  </ExtendedData> <Point> <coordinates>-122.000,37.002</coordinates> </Point> </Placemark> <Placemark> <name>Difficult trail</name> <ExtendedData> <SchemaData schemaUrl="#TrailHeadTypeId">  <SimpleData name="TrailHeadName">Mount Everest</SimpleData> <SimpleData name="TrailLength">347.45</SimpleData> <SimpleData name="ElevationGain">10000</SimpleData> </SchemaData> </ExtendedData> <Point> <coordinates>-121.998,37.0078</coordinates> </Point> </Placemark> </Document> </kml>

バルーンのデフォルトのスタイルを使用した SchemaData の例

displayName のエンティティ置換

Schema と SchemaData を使用する方法でも、<BalloonStyle> 要素の <text> 要素でのエンティティ置換がサポートされます。

<Schema> の <displayName> を使用すると、カスタムデータ型をユーザーにわかりやすい名前で表示できます。Schema でこの文字列を変更すると、その型を含むすべての Feature の <displayName> が変更されます。

<BalloonStyle> 要素の <text> 要素では、<displayName> を修飾するために次の構文を使用します:

$[TYPENAME/TYPEFIELD/displayName]

計算式の説明

TYPENAME: <Schema> の name 属性
TYPEFIELD: <SimpleField> の name 属性
displayName: <SimpleField> 内の <displayName> 要素

次のコードでは、前述の SchemaData の例に BalloonStyle テンプレートを追加しています。ゴルフコースの例と同じように、Document の冒頭で <Style>、<BalloonStyle>、<text> 要素を使用してテンプレートを作成しています。ファイル内の各 Placemark は、このスタイルテンプレート「ExtendedData+SchemaData」を参照します。

<kml xmlns="http://www.opengis.net/kml/2.2"> 
<Document>   
  <name>ExtendedData+SchemaData</name>   
  <open>1</open>    
  <!-- Create a balloon template referring to the user-defined type -->
  <Style id="trailhead-balloon-template">     
    <BalloonStyle>       
      <text>
        <![CDATA[         
          <h2>My favorite trails!</h2>         
          <br/><br/>         
          The $[TrailHeadType/TrailHeadName/displayName] is <i>$[TrailHeadType/TrailHeadName]</i>.        
          The trail is $[TrailHeadType/TrailLength] miles.         <br/>        
          The climb is $[TrailHeadType/ElevationGain] meters.         <br/><br/>       
        ]]>
      </text>     
    </BalloonStyle>
  </Style>     

  <!-- Declare the type "TrailHeadType" with 3 fields -->
  <Schema name="TrailHeadType" id="TrailHeadTypeId">     
    <SimpleField type="string" name="TrailHeadName">       
      <displayName><![CDATA[<b>Trail Head Name</b>]]></displayName>     
    </SimpleField>     
    <SimpleField type="double" name="TrailLength">       
      <displayName><![CDATA[<i>The length in miles</i>]]></displayName>     
    </SimpleField>     
    <SimpleField type="int" name="ElevationGain">       
      <displayName><![CDATA[<i>change in altitude</i>]]></displayName>     
    </SimpleField>   
  </Schema>       

  <!-- Instantiate some Placemarks extended with TrailHeadType fields -->    
  <Placemark>     
    <name>Easy trail</name>     
    <styleUrl>#trailhead-balloon-template</styleUrl>     
    <ExtendedData>       
      <SchemaData schemaUrl="#TrailHeadTypeId">        
        <SimpleData name="TrailHeadName">Pi in the sky</SimpleData>         
        <SimpleData name="TrailLength">3.14159</SimpleData>         
        <SimpleData name="ElevationGain">10</SimpleData>       
      </SchemaData>     
    </ExtendedData>     
    <Point>       
      <coordinates>-122.000,37.002</coordinates>     
    </Point>   
  </Placemark>    
  <Placemark>     
    <name>Difficult trail</name>     
    <styleUrl>#trailhead-balloon-template</styleUrl>     
    <ExtendedData>
      <SchemaData schemaUrl="#TrailHeadTypeId">         
        <SimpleData name="TrailHeadName">Mount Everest</SimpleData>        
        <SimpleData name="TrailLength">347.45</SimpleData>         
        <SimpleData name="ElevationGain">10000</SimpleData>       
      </SchemaData>    
    </ExtendedData>    
    <Point>       
      <coordinates>-121.998,37.0078</coordinates>     
    </Point>   
  </Placemark>   
</Document> 
</kml>

BalloonStyle テンプレートを使用した SchemaData の例

BalloonStyle テンプレートを使用して作成したバルーンを、前のセクションの画面キャプチャに示した同じデータのデフォルトバルーンスタイルと比較してみてください。

Feature への任意の XML データの追加

ユーザーデータを Feature に追加する最も簡単な方法は、データを <ExtendedData> の値として直接追加する方法です。Google Earth では、このデータは保存されますが処理はされません。

この方法で追加されたカスタムデータ要素には、「名前空間接頭辞」（xmlns:prefix="namespace"）を含める必要があります。この接頭辞は、<kml> 要素または <ExtendedData> 要素に追加できます。外部の名前空間接頭辞は、次の例に示すように、ユーザーデータのインスタンスごとに修飾する必要があります:

<kml xmlns="http://www.opengis.net/kml/2.2">
<Document>
  <name>ExtendedData Test</name>
  <Placemark>
    <name>CampsiteData</name>
    <!-- Imported schema requires use of namespace prefix -->
    <ExtendedData xmlns:camp="http://campsites.com">
      <camp:number>14</camp:number>
      <camp:parkingSpaces>2</camp:parkingSpaces>
      <camp:tentSites>4</camp:tentSites>
    </ExtendedData>
    <Point>
      <coordinates>-114.041,53.7199</coordinates>
    </Point>
  </Placemark>
</Document>
</kml>

トップへ戻る

カスタム データの追加