Google Earth API开发者指南
Google Earth API开发者指南
简介
欢迎阅读Google Earth API开发者文档。使用Google地球插件及其JavaScript API，您可以在网页中嵌入功能完备的Google地球及其3D呈现功能。与Google Maps API一样，您可以绘制标记和线条，不过是3D的哦！
如果您阅读完本开发者指南后有任何关于API的问题，请访问Google Earth API开发者论坛。
受众
本文档面向熟悉JavaScript编程和面向对象编程概念的用户。Google Earth API是以KML为模型设计的，因此您还应查阅Google的KML文档。
Google地球插件
目前，Google地球插件可以在以下平台上使用：
-
Microsoft Windows（XP和Vista）
- Google Chrome 5.0及以上版本
- Internet Explorer 7.0及以上版本
- Firefox 3.0及以上版本
- Flock 1.0及以上版本
-
Apple Mac OS X 10.5及以上版本(Intel)
- Google Chrome 5.0及以上版本
- Safari 3.1及以上版本
- Firefox 3.0及以上版本
尽管在另外一些支持带有npruntime扩展程序的NPAPI的浏览器上，Google地球插件和API也可能会正常运行，但这些浏览器并不属于官方支持范围。
安装
要安装Google地球插件，请访问包含该插件的任意网页（例如 http://code.google.com/apis/ajax/playground/#hello,_earth）。
在为您的浏览器安装插件之前，系统可能会请求许可，请点击以允许安装。安装完毕后，您可能需要刷新网页，插件才能正确显示。
卸载
- Windows：依次选择开始 > 程序（或所有程序）>Google地球 > 卸载Google地球插件。
-
Mac：先删除
/Library/Internet Plug-ins/Google Earth Web Plug-in.plugin，然后重新启动浏览器。
使用Google Earth API
要在网页中加载Google地球插件，您需要执行以下操作：
- 加载Google Earth API。
- 创建用于包含该插件的DIV元素。
- 创建用于初始化插件的函数。
- 网页加载完毕后，调用该初始化函数。
下文会对这些步骤进行说明。
注意：如果您想使用Google Maps API for Business授权许可的Google Earth API，请参阅Google Maps API for Business开发者指南，了解更多信息。
加载Google Earth API
请将以下标记放置在HTML页面的 <head> 部分：
<scripttype="text/javascript"src="https://www.google.com/jsapi"></script>
该标记的src指向包含一个方法（google.load，用于加载各个Google API）的 JavaScript 文件。在新的<script>标记中调用以下函数：
google.load("earth","1",{"other_params":"sensor=true_or_false"});
该函数用于告知Google将earth模块加载到google.earth命名空间，同时指定使用版本1（API的最新稳定版本）。要指定最新的API测试版本，请指定为"1.x"。
该函数必须添加sensor参数，指明此应用否会使用GPS定位器等传感器来确定用户的位置。在此示例中，我们将该参数值设为变量“true_or_false”，用于提醒您必须将该值明确设为true或false。
要详细了解加载机制，请参阅Google AJAX API文档。
为插件创建容器
Google地球插件会加载到具有唯一ID的DIV元素中。将此DIV添加到网页的<body>部分：
<divid="map3d"style="height:400px;width:600px;"></div>
在以上示例中，名为map3d的DIV将会成为插件的目标元素。
创建初始化函数
在此步骤中，您要创建三个函数。它们将按顺序完成以下操作：
- 第一个函数尝试创建新的插件实例。
- 在成功创建插件实例后调用第二个函数。
- 在未能创建实例时调用第三个函数。
第一个函数如下所示：
function init(){
google.earth.createInstance(\'map3d\', initCB, failureCB);
}
此处的google.earth.createInstance显示了三个选项：应将实例添加到其中的DIV元素、返回成功时要调用的函数以及返回失败时要调用的函数。除了上述选项以外，您还可以指定一个要建立连接的备用数据库，以便显示火星图像或连接至Google地球企业版数据库。
成功回调函数将包含设置“首次运行”体验所需的全部代码：在浏览器中加载插件实例时将首先显示的所有对象和视图。必须在此函数中添加GEWindow.setVisibility方法，并将窗口显示状态设置为true，这样插件才能显示在对应的DIV中：
function initCB(instance){
ge = instance;
ge.getWindow().setVisibility(true);
}
失败回调可包含任何用于处理失败以创建插件实例的代码。错误代码将传递到回调函数，并且可根据需要在网页上或作为警告重复显示。在本指南中，错误回调函数均已留空：
function failureCB(errorCode){
}
网页加载完毕后调用初始化函数
Google命名空间包含setOnLoadCallback()函数，用于在HTML网页和请求的API加载完毕后调用指定的函数。使用此函数可确保只有在网页DOM完全扩展后才加载插件。
google.setOnLoadCallback(init);
完整示例
<html>
<head>
<title>示例</title>
<scripttype="text/javascript"src="https://www.google.com/jsapi"></script>
<scripttype="text/javascript">
var ge;
google.load("earth","1",{"other_params":"sensor=true_or_false"});
function init(){
google.earth.createInstance(\'map3d\', initCB, failureCB);
}
function initCB(instance){
ge = instance;
ge.getWindow().setVisibility(true);
}
function failureCB(errorCode){
}
google.setOnLoadCallback(init);
</script>
</head>
<body>
<divid="map3d"style="height:400px;width:600px;"></div>
</body>
</html>
加载其他数据库
您可以加载自己的数据库，使其显示在Google地球的球体上，方法有两种：一是在初始化过程中指定该数据库，二是针对地球对象调用addSideDatabase()。如果在初始化阶段加载数据库，则系统只会加载此数据库，而不会加载标准的Google地球图像。
要在初始化插件时加载数据库，请使用以下代码：
function init(){
google.earth.createInstance(\'map3d\', initCB, failureCB,{
database:\'http://khmdb.google.com/?db=moon\',
username:\'\',
password:\'\'// 如果您的服务器需要这些。
});
}
使用 addSideDatabase()：
google.earth.addSideDatabase(
ge,\'http://khmdb.google.com/?db=mars\',
sideDatabaseSuccess,
sideDatabaseFail,
{
userName:\'\',
password:\'\'
}
);
要详细了解上述示例中显示的火星和月球数据库，请参阅本指南的星空、火星和月球章节。
断开与其他数据库的连接
要断开与其他数据库的连接，请针对其他数据库对象调用logout()：
sideDB.logout()
由于必须要有数据库指针，因此用户必须使用addSideDatabase()添加其他数据库：
var sideDB;
google.earth.addSideDatabase(
ge,\'http://khmdb.google.com/?db=mars\',
sideDatabaseSuccess,
sideDatabaseFail,
{
userName:\'\',
password:\'\'
}
);
function sideDatabaseSuccess(db){
sideDB = db;
}
function sideDatabaseDisconnect(){
sideDB.logout();
}
Google Maps Engine 地图
请注意：Google Maps Engine使用“地图”一词来指代图像和矢量层的集合；它相当于Google地球企业融合专业版中的“数据库”。有关详情，请参阅针对Google地球企业版用户的提示支持文章的术语部分。
Google Maps Engine地图可以使用上述方法加载到插件中。要获取指向指定地图的网址，您可以在任意已发布地图的详细信息页面上，点击发布的链接部分中的Google地球选项。
google.earth.addSideDatabase(
ge,\'https://earthbuilder.google.com/10446176163891957399-13516001307527776624-4/kh/\',
sideDatabaseSuccess,
sideDatabaseFail,
{
userName:\'\',
password:\'\'
}
);
查看示例：https://developers.google.com/earth/documentation/samples/addSideDatabase_noauth
如果您的地图是公开显示的，则您无需再执行其他步骤。如果您的地图是私有的，则您需要提供身份验证凭据。
Google Maps Engine地图身份验证
如果您已授予用户访问Maps Engine的权限，那么他们就可以使用自己的Google帐户针对您的地图进行身份验证。上述操作可利用OAuth 2.0令牌完成；有关详情，请参阅OAuth 2.0文档。
以下示例展示了如何利用OAuth 2.0令牌加载Earth API。您需要提供以下内容：
- 应用ID，通过API控制台的API访问页面获取。
- 有效的重定向URI，同样在API控制台中进行配置。在以下示例中，假设重定向URI的设定值与应用URI的值相同（即身份验证完毕后，身份验证流程便会让用户返回到原始页面）。
var ge;
//Google Maps APIfor Business 用户在加载Google Earth API时
// 必须指定自己的客户端 ID
// var params = {"other_params":"client=YOUR_MAPSFORBUSINESS_CLIENTID&sensor=false"};
var params ={"other_params":"sensor=false"};
google.load("earth","1", params);
function init(){
var hash_value = window.location.hash;
if(!hash_value){
var redirect_url ="https://accounts.google.com/o/oauth2/auth";
// 以下client_id值是通过API控制台获取的。
// 它不同于Google Maps APIfor Business 客户端 ID。
redirect_url +="?client_id=370755043334.apps.googleusercontent.com";
redirect_url +="&redirect_uri="+ window.location.href;
redirect_url +="&scope=https://www.googleapis.com/auth/earthbuilder.readonly"
+"%20https://www.googleapis.com/auth/userinfo.email";
redirect_url +="&response_type=token";
window.location = redirect_url;
return;
}
if(hash_value[0]=="#"){
hash_value = hash_value.slice(1);
}
var hash_parts = hash_value.split("&");
for(var i =0; i < hash_parts.length;++i){
var name_value = hash_parts[i].split("=");
if(name_value.length ==2){
var name = name_value[0];
var value = name_value[1];
if(name =="access_token"){
g_oauth_token_value = value;
}
}
}
if(!g_oauth_token_value){
return;
}
var optArgs ={
oauth2Info :{
oauthToken: g_oauth_token_value,
signingUrl:\'https://earthbuilder.google.com/\'
}
};
google.earth.createInstance(\'map3d\', initCB, failureCB, optArgs);
}
function initCB(instance){
ge = instance;
ge.getWindow().setVisibility(true);
ge.getOptions().setStatusBarVisibility(true);
ge.getNavigationControl().setVisibility(ge.VISIBILITY_AUTO);
ge.getLayerRoot().enableLayerById(ge.LAYER_BORDERS,true);
ge.getLayerRoot().enableLayerById(ge.LAYER_ROADS,true);
var lookAt = ge.createLookAt(\'\');
lookAt.setLatitude(41.26);
lookAt.setLongitude(-100.00);
lookAt.setRange(800000.0);
ge.getView().setAbstractView(lookAt);
// 使用以下有效的Maps Engine网址进行替换。
// 通过点击发布的链接部分（位于详细信息页面上）的Google地球选项
// 可以获取该网址。
var earthDb =\'https://earthbuilder.google.com/01234-5678-9/kh/\';
google.earth.addSideDatabase(
ge, earthDb,
sideDatabaseSuccess,
sideDatabaseFail,
{
userName:\'\',
password:\'\'
}
);
}
function failureCB(errorCode){
alert(errorCode);
}
function sideDatabaseSuccess(db){
db.setDrawOrder(2);
}
function sideDatabaseFail(){
alert(\'Failed to add side database connection.\');
}
google.setOnLoadCallback(init);
Google Maps API for Business客户端ID
如果您是Google Maps APIfor Business客户，则必须在加载API时传递客户端ID。
var params ={"other_params":"client=YOUR_MAPSFORBUSINESS_CLIENTID&sensor=false"};
google.load("earth","1", params);
问题排查
如果您的代码不起作用，则可以参考以下某些方法来解决您遇到的问题：
- 使用JavaScript调试程序。如需获取详细信息（包括常见应用列表），请参阅本指南的调试部分。
- 查找拼写错误。请注意，JavaScript语言区分大小写。
- 搜索开发者论坛。如果您找不到可以解答您问题的帖子，请在该论坛中发帖提问，并在帖子中附上指向能够演示相关问题的网页的链接。
- 要获取更多开发者资源，请参阅其他资源。
其他资源
本指南包含大量工作示例，这些示例链接自相关代码示例上方的资源行。除了本文档中提供的示例以外，以下资源也包含许多示例：
- AJAX API园地 - 可直接在网页上进行编辑的交互式示例精选。可以导出您的代码，并将其另存为JavaScript或HTML。
- Earth API演示库 - 一系列Earth API演示和示例，包括社区提供的内容。
- 基本示例 - 借助这些包含完整HTML的独立示例研究单个API功能。
如果您需要了解有关Google地球、KML或Google地图的详情，请参阅以下内容：
开发者版本
用户可通过以下网址下载开发者版本的插件：http://earth.google.com/plugin/download-dev-plugin.html。在发布常规版本之前，此版本的插件可能会添加一些新功能；但此版本的稳定性不高，随时可能会删除那些仅针对开发者版本推出的功能。
- 本指南的开发者版本一章说明了开发者版本的各项功能。
- 您可以通过以下网址访问专门针对开发者版本的插件的论坛：https://groups.google.com/group/earth-api-developer-channel。