ZKSforce 版本 58.0.0

ZKSforce 58.0.0

×

测试已测试✓
语言语言 Obj-CObjective C
许可证 MIT
发布上次发布2023年8月

由 Simon Fell 维护。

ZKSforce 58.0.0

  • 作者
  • Simon Fell

ZKSforce Build Status

ZKSforce 是一个 Cocoa 库，用于调用 Salesforce.com 网络服务 API，易于将 Salesforce 集成到您的 MacOSX 和 iOS 项目中。（支持 MacOSX 10.9+，iOS 9+）

ZKSforce 支持所有合作伙伴网络服务 API，包括

  • 登录，getUserInfo，serverTimestamp，setPassword，resetPassword
  • describeGlobal，describeSObject，describeLayout，describeTabs 及其他描述。
  • 创建，更新，删除，undelete，合并，upsert，convertLead
  • 搜索，查询，queryAll，queryMore，检索，处理。
  • 合作伙伴 API 的所有其他内容。
  • 支持刷新令牌的 OAuth

客户端通常就像网络服务 API 一样工作，但是它在一些地方做一些让生活变得更简单的智能操作。

  • 它将跟踪会话的持续时间并在需要时重新登录，所以只需按照需要调用方法，无需担心会话 expires away from under you。
  • 在 ZKDescribeSObject 中有一个帮助方法，根据字段名称获取 ZKDescribeField。
  • 在 ZKSObject 中，fieldsToNull 集合由您管理，如果通过 setFieldToNull 将字段添加到 fieldsToNull 集合中，它将自动删除任何字段值；您还可以直接在 setFieldValue:field: 中设置字段值为 nil（即 null），它将自动将其转换为 fieldsToNull 调用。
  • ZKQueryResult 实现了 NSTableView 非正式数据源接口，因此您可以在表格视图中轻松显示查询结果（就像 SoqlX 所做的那样）
  • 您可以通过调用 setCacheDescribes 让 ZKSforceClient 对象自动为您缓存 describeGlobal/describeSObject 结果。

使用非常直接，创建 ZKSforceClient 类的实例，调用 login，然后根据需要调用其他操作。所有可能引起 HTTP 请求的调用都使用基于异步块的方法。例如：

    ZKSforceClient *sforce = [[ZKSforceClient alloc] init];
    [sforce login:username password:password
		failBlock:^(NSError *err) {
			[[NSAlert alertWithError:err] runModal];
		}
		CompleteBlock:^(ZKLoginResult *result) {
			NSLog(@"Hello %@", result.userInfo.userFullName);
	}]

所有回调块都在主线程/队列上运行。如果你希望回调在特定的队列上运行，每个API调用都有一个版本可以设置额外的队列参数来指定回调队列。

一旦登录成功，你可以使用其他方法，例如创建一个新的联系人类，通过构建ZKSObject实例，填写字段值，然后调用创建方法。

    ZKSObject *contact = [ZKSObject withType:@"Contact"];
    [contact setFieldValue:@"Fell" field:@"LastName"];
    [contact setFieldValue:@"Simon" field:@"FirstName"];
    [sforce create:@[contact]
		failBlock:^(NSError *err) {
			[[NSAlert alertWithError:err] runModal];
		}
		CompleteBlock:^(NSArray *result) {
	        ZKSaveResult *sr = result[0];
			if ([sr success])
				NSLog(@"new contact id %@", [sr id]);
			else
				NSLog(@"error creating contact %@ %@", [sr statusCode], [sr message]);
		}
	];

除了传统的用户名和密码登录，还支持基于OAuth的认证方式，你可以将OAuth登录流程结束后收到的最终回调URL传递给它，它会自动从中提取所需的所有参数。

	ZKSforceClient *sforce = [[ZKSforceClient alloc] init];
	NSError *err = [sforce loginFromOAuthCallbackUrl:callbackUrl oAuthConsumerKey:OAUTH_CLIENTID];
	if (err != nill) {
	    [[NSAlert alertWithError:err] runModal];
	    return;
	}
	// use as normal

你需要将刷新令牌和认证主机存储在一个安全的地方，比如钥匙链。然后当您重新启动时，可以将这些传递给ZKSforceClient以初始化它。它会自动使用刷新令牌服务以获取新的sessionId。

ZKSforceClient *sforce = [[ZKSforceClient alloc] init];
[sforce loginWithRefreshToken:refreshToken authUrl:authHost oAuthConsumerKey:OAUTH_CLIENTID
		failBlock:^(NSError *err) {
			[[NSAlert alertWithError:err] runModal];
		}
        completeBlock:^{
			NSLog(@"Successfully initialized from refresh token");
}];
// See the OAuthDemo sample for more info.

日期/时间格式

日期/时间序列化方式在v35.0.2中发生了变化。通过网络发送的时间戳现在是UTC时间，而之前发送的时间戳是在用户的本地时区（应用正确的偏移量）中。发送的相同逻辑时间戳，但在序列化的日期时间中的偏移量有所不同。如果你出于某些原因自己调用ZKSoapDate的asString方法，那么生成的字符串是不同的。[尽管我不太明白你为什么这样做]。

单元测试

zkSforceTests目录包含一个包含多个测试的项目，这些测试主要针对手动编写的辅助类，通常不测试从WSDL生成的代码类。

从旧版本更新

通常，当Salesforce API更新时，ZKSforce也会更新，通常每年更新2到3次。大多数时候，更改仅限于映射Salesforce API更改的那些更改。有时也会进行较大的结构性更改。Salesforce对API有强大的版本控制策略，所以如果你的应用程序运行正常，就没有必要持续升级，只有在你需要利用某些API添加时才进行升级。

版本 v51 的重大更改

从复杂的类型在 WSDL 中生成的类有一些更改。

  • 它们现在遵循一个单一模式。以前，它们的结构根据使用方式而不同（有仅用于反序列化、仅用于序列化和两者都用的变体）。
  • 现在所有 WSDL 中的类型都有为它们生成的类，之前只有可从操作到达的类型包括在内。
  • 一些 WSDL 元数据现在可以通过每个类上的 wsdlSchema 方法以编程方式获取。
  • 它们不再实现 NSCopying。
  • 属性访问器已从原子更改为非原子。
  • 已更新 NSArray 属性，以包括其包含的类型，例如 NSArray

版本 v47 的重大更改

版本 v47 是一项重大更改，清除了一些操作系统 API 的弃用，并将 Objective-C API 完全现代化，以使用异步方法，对于所有可能导致网络请求的请求使用 block。如果您从早期版本迁移并已采用基于异步 / block 的方法，那么您有一些小更改要处理

  • 异步方法名称已从 performXXXX 更改为 XXXX，例如 performDescribeGlobal 现在是 describeGlobal。
  • failBlock 现在使用 NSError 而不是 NSException。

如果您是从更早的版本迁移而来并且仍在使用同步 API 调用，那么您面前还有更多工作要做。

  • 所有导致网络请求的同步方法都已消失，被使用回调 block 的异步版本所取代。默认情况下，这些回调在主线程/队列上执行，因此应该很容易迁移。
  • 以前通过抛出异常报告的错误条件现在都通过 failBlock 回调报告，该回调传递一个包含失败原因的 NSError。

无论您使用哪种 API 样式，还有一些其他更改。

  • 搜索的结果类型现在与 WSDL 完全匹配。
  • ZKBaseClient 代理将成功和错误情况合并到单个调用中。
  • ZKSforceClient 不再实现 copyWithZone:，现在可以安全地同时从多个线程/队列中使用。
  • 文件名和类型现在具有其 ZK 前缀的一致大写。
  • 文件已经重新排列成一组目录。

版本 v44 的重大更改

版本 v44 包括了一些更改，以采用 ARC 和现代 Objective-C 功能。

v29版本的主要更改

v29是一个重大更新，其中大量代码现在是来自合作伙伴WSDL生成的代码，因此可能有许多API更改，可能会影响尝试更新到这个版本的zkSforce的现有项目。

  • 一些文件的文件名大小写已经修复，以匹配类名（例如，zkChildRelationship.h现在是ZKChildRelationship.h）
  • ZKDescribeLayout上的Id属性现在称为id
  • ZKSaveResult上的message和statusCode属性已被移动到Extra分类/文件中
  • ZKRelatedList上的describe和fieldsColumnNames属性已被移动到Extra分类/文件中
  • ZKUserInfo上的许多属性现在都在Extra分类/文件中
  • ZKUserInfo的licenseType已被删除（它不再在API中）
  • ZKPicklistEntry上的validFor现在返回NSData而不是NSString
  • setPassword的签名已从setPassword:forUserId:更改到setPassword:userId
  • delete现在返回ZKDeleteResult的NSArray而不是ZKSaveResult的NSArray（注意这两种类型都具有相同的属性）
  • serverTimestamp方法已被getServerTimestamp取代，并现在返回带有timestamp成员（类型为NSDate）的ZKGetServerTimestampResult类，而不是返回一个字符串
  • ZKDescribeLayoutComponent上的componentType枚举已被删除
  • ZKDecribeGlobalSObject上的defaultOnCreate现在是defaultedOnCreate，undeleteable现在是undeletable，deleteable现在是deletable
  • 在OSX上，需要将Security框架添加到要链接的框架列表中。

通过CocoaPods设置项目

将ZKSforce集成到您的应用的 easiest way 是使用 CocoaPods， Cocoa 依赖管理框架，只需创建一个Podfile，例如

platform :osx
pod 'ZKSforce', '~> 51.0.0'

然后运行 pod install myApp.xcodeproj

手动设置项目

为了支持在OSX和iOS上使用，该库使用libxml作为其XML解析器，而不是NSXML，后者在iOS上未完全实现。一旦将所有.h和.m文件添加到项目中，您需要转到构建设置，并将/usr/include/libxml2添加到头文件搜索路径，并将libxml2.dylib添加到链接框架部分。然后您应该就可以使用了。对于OSX，您还需要将Security框架添加到链接的框架列表中。有关这些步骤的详细说明见Wiki。