Google Maps Android API v2开发文档翻译：入门，Getting Started

要想使用地图接口来访问Google Maps 服务器的话，妳需要向妳的程序中加入一个地图接口密钥。密钥是免费的，妳可以在任何调用地图接口的程序中使用它，并且它支持无限数量的用户。妳提供自己的程序的签名证书和软件包名字，以此来从Google APIs Console 获取一个地图接口密钥。向妳的程序的AndroidManifest.xml 文件中加入一个元素，以此来将这个密钥添加到程序中。

妳需要了解Android 的发布流程和条件，才能理解清楚注册妳的程序及获取密钥的过程。总的来说，所有的Android程序都必须使用一个数字证书来签名，而妳保有这个证书的私钥。因为数字签名都是唯一的，所以就可以以一种简单的手段来唯一地识别出妳的程序。因此，可用来在Google Play Store 这样的系统中跟踪妳的程序，以及跟踪妳的程序对某些资源的使用情况，例如Google Maps 服务器。

注意：参考Android开发指南中的对妳的程序进行签名以了解关于数字证书的更多信息。

地图接口密钥是与特定的证书/软件包组合对应起来的，而不是与用户或程序对应起来的。对于同一个证书，妳只需要一个密钥，无论妳的程序有多少用户。使用相同证书的程序可以使用同一个接口密钥。然而，我们建议，对于每个程序，都使用一个不同的证书来签名，以此来获取不同的密钥。

为程序获取一个密钥，这需要多个步骤。以下是这些步骤的列表，之后将详细说明每一个步骤。

1.获取妳的程序的证书信息。
2.在 Google APIs Console 上注册一个项目，并且将地图接口作为服务添加进去。
3.请求获取一个或多个密钥。
4.将密钥添加到妳的程序中，然后开始开发。

显示妳的程序的证书信息

地图接口密钥是以妳的程序的数字证书的一部分缩略信息为基础的，这个信息被称为SHA-1指纹。T这个指纹是使用常用的SHA-1 散列算法计算出来的一个唯一的文字串。因为指纹本身是唯一的，所以，Google Maps使用它来唯一地识别妳的程序。

要想显示出妳的证书的SHA-1 指纹的话，首先要确保妳在使用正确的证书。妳可能会有两个证书：

•. 调试（Debug）证书：在以下情况下，Android SDK工具会自动生成这个证书：当妳在命令行做一次“调试”编译时；或者当妳在没有将它导出为发布版的程序的情况下在Eclipse 中运行一个项目时。只能在正在测试的程序中使用这个证书；不要尝试发布一个以调试版本的证书签名的程序。调试版本的证书，在 Android 开发者文档的在调试模式下签名小节中有详细说明。
•. 发布（Release）证书：当妳使用ant 程序或Eclipse 来做一次“发布”编译时，Android SDK工具会生成这个证书。妳也可以使用keytool 程序来生成这个证书。当妳准备将妳的程序发布给整个世界时，就使用这个证书。

妳可以使用keytool 程序的-v参数来显示出一个证书的SHA-1 指纹。要想了解更多关于Keytool的信息，就参考这里的文档http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html。

显示调试版证书的指纹

1.找到妳的调试版密钥存储（keystore）文件。文件名是debug.keystore，是在妳第一次构建妳的项目时创建的。默认情况下，它被储存在与妳的Android 虚拟设备文件(AVD)相同的目录中：

- •. OS X and Linux: ~/.android/
如果妳在使用Eclipse 及ADT，而妳不确定妳的调试版密钥存储文件是放在哪里，则，单击窗口 > 首选项 > Android > Build 以查看完整路径，然后妳可以将路径粘贴到一个文件管理器里去，以找到包含有密钥存储文件的目录。

1.列出SHA-1 指纹。

- •.对于Linux或OS X，打开一个终端窗口，输入以下命令：
  
  keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android
2.妳应当看到类似下面这样的输出内容：

Alias name: androiddebugkey

Creation date: Jan 01, 2013

Entry type: PrivateKeyEntry

Certificate chain length: 1

Certificate[1]:

Owner: CN=Android Debug, O=Android, C=US

Issuer: CN=Android Debug, O=Android, C=US

Serial number: 4aa9b300

Valid from: Mon Jan 01 08:04:04 UTC 2013 until: Mon Jan 01 18:04:04 PST 2033

Certificate fingerprints:

MD5: AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6A:AC:F9

SHA1: BB:0D:AC:74:D3:21:E1:43:07:71:9B:62:90:AF:A1:66:6E:44:5D:75

Signature algorithm name: SHA1withRSA

Version: 3

以SHA1 开头的那一行中包含有这个证书的SHA-1 指纹。指纹是由20个双字节的十六进制数字组成的，每两个双字节数字之间使用冒号分隔。

显示发布版证书的指纹

找到妳的发布版证书密钥存储文件。对于发布版的证书，没有默认的位置和文件名。如果妳在构建发布版程序时没有指定证书，则，所以产生出来的.apk就是未签名的，这样妳就必须在发布之前对它进行签名。对于发布版的证书，妳也需要该证书的别名和该证书的密钥存储文件的密码。妳可使用以下命令来列出一个密钥存储文件中所有密钥的别名：

keytool -list -keystore your_keystore_name

用妳当前的密钥存储文件的完整的路径来替换命令中的your_keystore_name，并且要带.keystore扩展名。程序会提示妳输入这个密钥存储文件的密码。当妳输入了密码之后，keytool就会显示出这个密钥存储文件中所有的别名。
1.在终端中输入以下命令：

keytool -list -v -keystore your_keystore_name -alias your_alias_name

用妳当前的密钥存储文件的完整的路径来替换命令中的your_keystore_name，并且要带.keystore扩展名。使用妳在创建这个证书时赋予的别名来替换掉命令中的your_alias_name。

警告：为了保护妳的密钥存储文件和密钥，不要在命令行中输入storepass 和keypass 参数，除非妳对自己电脑的安全性狠有信心。例如，在一个公用的电脑上，某人可以查看妳的终端窗口命令历史或者运行中的进程列表，拿到妳的密码，然后就可以对妳的签名证书做写入操作了。这将使得那个人可以修改或者完全将妳的程序替换成他/她们自己的。
2.妳会看到类似下面这样的输出内容：

Alias name: <alias_name>

Creation date: Feb 02, 2013

Entry type: PrivateKeyEntry

Certificate chain length: 1

Certificate[1]:

Owner: CN=Android Debug, O=Android, C=US

Issuer: CN=Android Debug, O=Android, C=US

Serial number: 4cc9b300

Valid from: Mon Feb 02 08:01:04 UTC 2013 until: Mon Feb 02 18:05:04 PST 2033

Certificate fingerprints:

MD5: AE:9F:95:D0:A6:86:89:BC:A8:70:BA:34:FF:6B:AC:F9

SHA1: BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:90:AF:A1:66:6E:44:5D:75

Signature algorithm name: SHA1withRSA

Version: 3

以SHA1 开头的那一行中包含有这个证书的SHA-1 指纹。指纹是由20个双字节的十六进制数字组成的，每两个双字节数字之间使用冒号分隔。

在Google APIs Console中创建一个API项目

按照以下步骤来在Google APIs Console 中为妳的程序创建或修改一个项目，并且注册地图接口。

1.打开浏览器，访问 Google APIs Consle。

- •.如果妳之前并没有使用过Google APIs Console，那么，网页会提示妳创建一个项目，妳将使用这个项目来跟踪妳对Google Maps Android API的使用情况。点击Create Project；控制台（Console）会创建一个叫做API Project 的新项目。在下一页中，这个名字会出现在左上角。点击这个名字，就可以改名，或者做别的项目管理工作。

- •.如果妳已经在使用Google APIs Console了，那么，妳会立即看到妳的已有项目的列表及可用的服务。最好还是使用一个新的项目来管理Google Maps Android API，所以，点击左上解的项目名字，然后点击Create。

1.妳将会在主窗口中看到一个接口和服务列表。如果没有看到，那么，在左边的导航条里点击Services。

1.在页面中央显示的服务列表中，往下拉动，找到Google Maps Android API v2。在那个条目的右边，点击那个开关，让它变成on。

1.将会显示Google Maps Android API Terms of Service。如果妳同意这个条款，那么就点击条款下面的复选框，然后点击Accept。然后妳就回到接口和服务列表了。

获取一个Google Maps API密钥

如果妳的程序已经注册到Google Maps Android API v2 服务了，那么妳就可以请求获取一个接口密钥。可以在一个项目里注册多个密钥。

1.在 Google APIs Console中找到妳的项目。
2.在左侧的导航条中，点击API Access。
3.在新的页面中，点击Create New Android Key...。
4.在弹出的对话框中，输入SHA-1 指纹，然后是一个分号，然后是妳的程序的软件包名字。例如：

BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75;com.example.android.mapexample
5.Google APIs Console会作出响应，显示出Key for Android apps (with certificates) 后面是一个40个字符的接口密钥，例如：

AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0

将这个接口密钥添加到妳的程序中

按照以下步骤来将接口密钥添加到妳的程序的清单中，即AndroidManifest.xml 文件中去。地图接口将从那里读取到密钥的值并且传送给Google Maps 服务器，于是就确认妳拥有访问Google Maps 数据的权限。

1.在AndroidManifest.xml中，将以下元素添加为 <application> 元素的子代元素，也就是说，直接将它插入到闭合标记</application>之前：

<meta-data

android:name="com.google.android.maps.v2.API_KEY"

android:value="API_KEY"/>

用妳自己的接口密钥来替换上面代码中的API_KEY。这个元素会将com.google.android.maps.v2.API_KEY 的值设置成API_KEY，并且使得妳的程序中所有的 MapFragment 都能读取到接口密钥。
2.保存AndroidManifest.xml，然后重新构建妳的程序。

在程序的清单文件中指定程序相关的设置

用到Google Maps Android API 的Android 程序应当在它的清单文件AndroidManifest.xml 中指定以下设置项：

•.这个程序要用到的地图接口密钥。这个密钥用于确认妳已经在Google APIs Console 中注册到了Google Maps 服务。如果妳是按照这个页面上说的步骤来操作的，那么，到现在为止，妳已经将接口密钥添加到清单文件中去了。
•.一些权限，使得这个程序可以访问Android 系统的一些功能及Google Maps 服务器。下面会有关于这些权限的说明。
•.(建议) 宣称本程序依赖OpenGL ES 版本2。外部的服务可检测到这个宣称，并且做出相应的处理。例如，Google Play Store不会在那些不支持OpenGL ES 版本2的设备上显示出这个程序。下面会有关于这个选项的说明。

特定权限

向 <manifest> 元素中加入一些子代元素 <uses-permission> ，以指定妳的程序所需要的权限。语法是这样的：

<uses-permission android:name="permission_name"/>

例如，要请求获得互联网访问权限，就加入这一行：

<uses-permission android:name="android.permission.INTERNET"/>

除了妳程序中其它部分所需要的权限之外，妳还需要声明以下与Google Maps Android API相关的权限：

•. android.permission.INTERNET 接口使用这个权限来从Google Maps 服务器上下载地图数据。
•. android.permission.ACCESS_NETWORK_STATE 接口需要检查连接状态，以决定是否可以下载数据。
•. com.google.android.providers.gsf.permission.READ_GSERVICES 使得接口可以访问到Google 的网页服务。
•. android.permission.WRITE_EXTERNAL_STORAGE 使得接口可以将地图数据缓存到设备的外部存储上。

建议声明以下权限，不过呢，如果妳的程序不需要确定用户的当前位置（通过代码来直接定位，或者是启用My Location 层）的话，就可以忽略掉。

•. android.permission.ACCESS_COARSE_LOCATION 使得接口可以通过无线网或移动基站数据（或二者同时使用）来确定设备的位置。
•. android.permission.ACCESS_FINE_LOCATION 使得接口可以通过全球定位系统（GPS）来精确地确定用户设备的位置。

<uses-permission android:name="android.permission.INTERNET"/>

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES"/>



<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

指定对OpenGL ES版本2的依赖

Google Maps Android API使用OpenGL ES版本2来渲染地图。如果没有安装OpenGL ES版本2，则，妳的地图就显示不出来。我们建议妳将以下这个 <uses-feature> 元素添加为AndroidManifest.xml 中 <manifest> 元素的一个子代元素：

<uses-feature

android:glEsVersion="0x00020000"

android:required="true"/>

这将会向外部服务宣称这个依赖关系。特别地，这将使得，在不支持OpenGL ES 版本2的设备上，Google Play Store 不会显示妳的这个程序。

添加一个地图

最简单地测试妳的程序是否配置正确的方式就是，添加一个简单的地图。妳需要修改2个文件：定义程序的界面的那个XML文件，以及定义程序主要逻辑的Java 文件。

请注意，以下的代码只能用于测试一下妳的以Android API 12 或更高版本为目标平台的程序是否配置正确。不应当在一个生产环境中的程序里直接使用这些代码。在这个教程及示例代码里，有一些示例，告诉妳怎么加入一些更稳健的代码。

1.将以下片断（fragment）加入到程序的布局XML 文件中。如果妳是在Eclipse 中使用Android Developer Tools (ADT)创建了一个'hello world'程序，那么对应的文件就是res/layout/activity-main.xml。使用以下代码来替换该文件中的全部内容。

<?xml version="1.0" encoding="utf-8"?>

<fragment xmlns:android="http://schemas.android.com/apk/res/android"

android:id="@+id/map"

android:layout_width="match_parent"

android:layout_height="match_parent"

android:name="com.google.android.gms.maps.MapFragment"/>
2.在MainActivity.java 中加入以下代码。

package com.example.mapdemo;

import android.app.Activity;

import android.os.Bundle;

public class MainActivity extends Activity {

@Override

protected void onCreate(Bundle savedInstanceState) {

super.onCreate(savedInstanceState);

setContentView(R.layout.activity_main);

}

}
3.构建并运行妳的程序。妳应当看到一个地图。如果没有看到地图，那么，检查并确认一下妳是否完成了这个页面上所说的全部步骤。

天体

Your opinions

Your name:

Email:Website url:Opinion content:

- no title specified

HxLauncher: Launch Android applications by voice commands