如何使用.NET Core开发对接Geotab服务器的Web API？

前置依赖准备 #

• 首先在你的.NET Core Web API项目中安装Geotab官方SDK，通过NuGet执行以下命令即可：

  dotnet add package Geotab.Checkmate.ObjectModel
  

不要自己手写HTTP请求对接Geotab原生接口，官方SDK已经封装了签名、认证、令牌刷新、错误重试等逻辑，能省90%的对接工作量

一、建立与Geotab服务器的稳定连接 #

推荐在项目启动时将Geotab API客户端注册为单例服务，复用连接避免重复认证带来的性能损耗，具体实现如下：

1. 先编写配置映射类，统一管理Geotab连接参数

public class GeotabApiSettings
{
    /// <summary>
    /// Geotab服务器地址，公有云默认是https://my.geotab.com，专属云替换为对应实例地址
    /// </summary>
    public string Server { get; set; }
    /// <summary>
    /// 租户数据库名称
    /// </summary>
    public string Database { get; set; }
    /// <summary>
    /// 认证账号
    /// </summary>
    public string User { get; set; }
    /// <summary>
    /// 认证密码/API Key
    /// </summary>
    public string Password { get; set; }
}

2. 在Program.cs中完成服务注册与初始化认证

// 从配置文件加载Geotab连接参数
builder.Services.Configure<GeotabApiSettings>(builder.Configuration.GetSection("GeotabSettings"));
var geotabConfig = builder.Configuration.GetSection("GeotabSettings").Get<GeotabApiSettings>();

// 注册Geotab API客户端为单例
builder.Services.AddSingleton<Geotab.Checkmate.API>(_ =>
{
    var apiClient = new Geotab.Checkmate.API(
        userName: geotabConfig.User,
        password: geotabConfig.Password,
        sessionId: null,
        database: geotabConfig.Database,
        server: geotabConfig.Server
    );
    // 初始化时完成身份认证
    apiClient.AuthenticateAsync().GetAwaiter().GetResult();
    return apiClient;
});

敏感配置（账号、密码、数据库名）不要硬编码在代码中，生产环境请使用环境变量、密钥管理服务存储，避免信息泄露

二、在Web API中调用Geotab接口完成业务对接 #

在控制器、业务服务层通过构造函数注入已经初始化好的Geotab API客户端，即可直接调用Geotab的所有开放接口，以下是两个高频使用的示例：

[ApiController]
[Route("api/geotab")]
public class GeotabBusinessController : ControllerBase
{
    private readonly Geotab.Checkmate.API _geotabClient;

    // 构造函数注入Geotab客户端
    public GeotabBusinessController(Geotab.Checkmate.API geotabClient)
    {
        _geotabClient = geotabClient;
    }

    /// <summary>
    /// 获取租户下所有车辆设备列表
    /// </summary>
    [HttpGet("devices")]
    public async Task<IActionResult> GetAllVehicleDevices()
    {
        var deviceList = await _geotabClient.CallAsync<List<Device>>(
            method: "Get",
            parameters: new { typeName = nameof(Device) }
        );
        // 按需返回字段，不要直接透传全量数据
        return Ok(deviceList.Select(d => new 
        {
            d.Id,
            d.Name,
            d.SerialNumber,
            Vin = d.VehicleIdentificationNumber,
            d.ActiveFrom,
            d.ActiveTo
        }));
    }

    /// <summary>
    /// 获取指定设备的最新GPS定位记录
    /// </summary>
    [HttpGet("device/{deviceId}/location")]
    public async Task<IActionResult> GetDeviceLatestLocation(string deviceId)
    {
        var locationRecords = await _geotabClient.CallAsync<List<LogRecord>>(
            method: "Get",
            parameters: new
            {
                typeName = nameof(LogRecord),
                search = new LogRecordSearch
                {
                    DeviceSearch = new DeviceSearch(deviceId),
                    // 查询参数统一使用UTC时间
                    FromDate = DateTime.UtcNow.AddHours(-2)
                },
                resultsLimit = 1
            }
        );
        var latestRecord = locationRecords.FirstOrDefault();
        if (latestRecord == null)
        {
            return NotFound("未查询到该设备近期的定位数据");
        }
        return Ok(new
        {
            latestRecord.Latitude,
            latestRecord.Longitude,
            latestRecord.Speed,
            latestRecord.Heading,
            RecordTime = latestRecord.DateTime
        });
    }
}

对接注意事项 #

• Geotab所有接口的时间参数、返回的时间字段均为UTC时区，业务侧需要根据所在区域自行做时区转换，不要直接传入本地时间作为查询条件
• 单例注册客户端即可，官方SDK会自动处理令牌过期刷新、错误重试逻辑，不需要每次请求新建客户端实例，否则会触发接口限流
• 批量拉取数据时单次请求的resultsLimit不要超过50000，数据量过大时分页拉取，避免请求超时
• 生产环境如果需要走代理访问公网，初始化API客户端时传入配置好代理规则的HttpClientHandler实例即可
• 生产环境建议使用Geotab后台生成的API Key代替账号密码做认证，可单独配置接口权限，安全性更高

内容的提问来源于stack exchange，提问作者Ravi vishwakarma