关于资产服务入门

与其他Predix平台服务类似，对资产服务的认证访问由指定的可信发布者控制，由用户账号和认证（UAA）网页服务管理。开始进行资产服务之前，UAA服务实例必须已经设置为可信发布者。
关于如何在Predix服务中实施认证和授权的更多信息，请参见了解平台服务。
资产服务设置
该路线图列出了开始进行资产服务的基本任务任务。
访问控制服务（ACS）的认证由指定的可信发布者控制，由用户账号和认证（UAA）网页服务管理。开始进行资产服务之前，您必须将一个UAA服务实例设置为可信发布者。关于在Predix服务中认证和授权的信息，请参见关于安全服务。
如果您已经根据使用Cloud Foundry命令设置平台服务中的描述设置了UAA服务，创建了一个可信的发布者和一个OAuth2客户端，那么您无需执行所有任务。
任务路线图
编号 任务 信息
1 创建一个文本文件，以存储您将来需要用到的数值。 请参见创建一个参数文本文件。
2 （可选）如有必要，配置您的代理设置。 根据您的位置和网络配置，您可能需要配置您的代理设置，以便访问远程资源。参见 定义与远程资源的代理连接。

3 （可选）设置对Predix平台Artifactory的访问。 如果您需要访问Predix平台程序工件，您需要设置对Artifactory的访问。
Predix提供ACS spring安全扩展，用于与spring安全进行集成。库存储在Artifactory中。
参见设置对Predix平台Artifactory的访问。

4 将您的应用程序部署到Cloud Foundry中。 关于将一个Predix Hello World网页应用程序部署到cloud foundry中的示例，请参见创建一个简单的Predix Hello World网页应用程序。

5 创建一个可信发布者的实例。 创建一个用户账号和认证（UAA）服务的实例。UAA是每个平台服务用于认证的授权服务器。
参见创建一个UAA服务实例。

6 创建一个资产服务实例。 参见创建一个资产服务实例。

7 创建OAuth2客户账号，设置对您的服务的访问，该服务使用UAA认证。 当您创建一个UAA实例时，会自动为您创建一个管理员客户端，用于访问UAA的其他配置。您可以为您的服务实例创建一个具有特定权限范围的新客户端。如果已经有一个Oauth2客户端，您可以更新该客户端以添加您的服务实例。
参见创建一个OAuth2客户端。

8 更新Oath2客户端以添加服务特定范围或权限。 为了使您的应用程序能够访问平台服务，您的JSON网络令牌（JWT）必须包含该平台服务所需的范围。
参见更新OAuth2客户端。
参见资产服务所需的权限与范围。

9 将您的应用程序与服务实例绑定。 如果要在您的应用程序与平台服务之间建立通信，你必须将应用程序与服务绑定。
参见将一个应用程序与一个资产服务实例绑定。

10 将资产模型数据添加到您的应用程序。 参见将资产模型数据添加到您的应用程序

11 开始使用资产服务。 参见使用资产服务。

创建一个参数文本文件
您可以在您的空间中创建多达10个UAA服务实例。如果您需要其他实例，添加新实例之前首先删除不用的旧实例。
1. 通过https://www.predix.io登录您的Predix账号。
2. 导航至目录 > 服务选项卡，然后点击用户账号和认证标题。
3. 在所需方案上点击订阅。
4. 填写新建服务实例页面上的字段。
字段 说明
组织 选择您的组织。
空间 为您的应用程序选择空间。
服务实例名称 为该UAA服务实例输入一个唯一的名称。
服务方案 选择一个方案。
管理员客户端密码 输入一个客户端密码（这是该UAA实例的管理员密码）。客户端密码可以是任意字母数字字符串。
注：将客户端密码记录在一个安全的位置，以供将来使用。
子域 （可选）除了为UAA创建的域，输入一个您可能需要用到的子域。您不得在子域的名称中添加特殊字符。子域的值不区分大小写。
5. 点击创建服务。
您的UAA实例使用以下规范创建：
• 一个客户端标识符（admin）。
注：一个 admin 客户端被创建用于启动引导。你可以创建与您的应用程序一起使用的其他客户端。
• 一个客户端密码（您在创建服务时指定的密码）。
如果要检索您的实例的其他详细信息，您可以将一个应用程序与您的实例绑定。
使用命令行创建一个UAA服务实例
使用命令行代替图形用户界面创建一个UAA服务实例的可选程序。
您可以在您的空间中创建多达10个UAA服务实例。如果您需要其他实例，您必须删除不用的旧实例并创建一个新实例。
1. 使用Cloud Foundry CLI登录Cloud Foundry。
cf login -a
的值在您注册Predix.io用户账号时收到的Predix欢迎电子邮件中。根据您注册的Predix.io， 的值为以下其中一个：
o Predix美国西部
https://api.system.aws-usw02-pr.ice.predix.io
o Predix美国东部
https://api.system.asv-pr.ice.predix.io
o Predix日本
https://api.system.aws-jp01-pr.ice.predix.io
o Predix英国
https://api.system.dc-uk01-pr.ice.predix.io
例如，
cf login -a https://api.system.aws-usw02-pr.ice.predix.io
2. 通过输入以下命令列出在Cloud Foundry市场中的服务。
cf marketplace
UAA服务 predix-uaa被列为其中一个可用服务。
3. 通过输入以下命令创建一个UAA实例。
cf create-service predix-uaa -c '{“adminClientSecret”:””,”subdomain”:””}'
其中：
o 是与服务相关的方案。例如，您可以将 tiered 方案用于 predix-uaa 服务。
o -c 选项用于指定以下其他参数。
 adminClientSecret 指定客户端密码。
 subdomain 指定一个除了为UAA创建的域您可能需要用到的子域。这是可选参数。您不得在子域的名称中添加特殊字符。子域的值不区分大小写。
注： Cloud Foundry CLI句法在Windows与Linux操作系统之间可能会不同。关于您的操作系统的适当句法，请参见Cloud Foundry帮助。例如，如果要查看 create service 命令的帮助，请运行 cf cs。
您的UAA实例使用以下规范创建：
• 一个客户端标识符（admin）。
注：一个 admin 客户端被创建用于启动引导。你可以创建与您的应用程序一起使用的其他客户端。
• 一个客户端密码（您在创建服务时指定的密码）。
如果要检索您的实例的其他详细信息，您可以将一个应用程序与您的实例绑定。
创建一个predix-uaa服务实例，客户端密码为admin，子域为ge-digital：
cf cs predix-uaa tiered test-1 -c '{“adminClientSecret”:”admin”,”subdomain”:”ge-digital”}'
VCAP_SERVICES中的内容为:
“VCAP_SERVICES”: {“predix-uaa”: [{“credentials”: {“issuerId”: “https://ge-digital.sb-uaa.grc-apps.svc.ice.ge.com/oauth/token“,”subdomain”: “ge-digital”,”uri”: “https://ge-digital.sb-uaa.grc-apps.svc.ice.ge.com“,”zone”: {“http-header-name”: “X-Identity-Zone-Id”,”http-header-value”: “011d56b9-831e-407d-98d0-da4c1c946862”}},”label”: “predix-uaa”,”name”: “test-1”,”plan”: “tiered”,”provider”: null,”syslog_drain_url”: null,”tags”: []}],
创建一个资产服务实例
创建一个资产服务实例，用于创建、更新并存储定义资产特性以及资产与其他建模元素之间关系的资产模型数据。
一个UAA服务实例已被配置为您的可信发布者。参见平台服务设置。
1. 通过https://www.predix.io登录您的Predix账号。
2. 导航至目录 > 服务选项卡，并点击资产数据服务标题。
3. 在所需方案上点击订阅。
4. 在新建服务实例页面上，输入：
字段 说明
组织 选择您的组织。
空间 为您的应用程序选择空间。
用户账号和认证（UAA） 选择一个现有的UAA实例或创建一个新的UAA实例。
参见创建一个UAA服务实例。

服务实例名称 为您的实例指定一个唯一的名称。
服务方案 选择一个方案。
5. 点击创建服务。
使用命令行创建一个资产服务实例
创建一个资产服务实例之前，您必须拥有该资产服务实例信任的UAA实例的基础URL。参见创建一个UAA服务实例。
注：使用Cloud Foundry CLI执行以下步骤。如果要在网页浏览器中完成这些步骤，请遵循Predix目录中服务页面上的说明。
1. 列出Cloud Foundry市场中的服务。
cf marketplace
资产服务 predix-asset作为一个可用服务列出。
2. 创建一个资产服务实例。
cf create-service predix-asset -c '{“trustedIssuerIds”:[“”, “”]}'
其中：
o 是与服务相关的方案。将 Tiered 用于 predix-asset 服务。
o 是您的可信发布者（UAA实例）的 issuerID 。例如， https://13fa0384-9e2a-48e2-9d06-2c95a1f4f5ea.predix-uaa.run.aws-usw02-pr.ice.predix.io/oauth/token。您可以使用一个逗号分隔列表指定多个可信发布者。您可以在将一个应用程序与一个UAA实例绑定之后从VCAP_SERVICES环境变量中检索该URL。
该消息表示资产实例已创建。将其与一个应用程序绑定之后，从VCAP_SERVICES环境变量中检索该资产服务实例的URI。
创建一个OAuth2客户端
创建其他OAuth2客户端以访问一个UAA实例的程序。
• 登录predix.io。
OAuth 2.0协议将一个客户端建立为一个应用程序，可以代表资源所有者并通过其授权执行保护资源请求。当您创建一个UAA实例时，会自动为您创建一个管理员客户端，能够配置您的UAA实例。管理员客户端的密码是您在创建UAA实例时指定的密码。您可以为认证具有相同UAA服务器实例的不同应用程序创建其他客户端。您可以根据您的应用程序的要求为每个客户端分配不同的访问许可。
1. 在控制台视图中，选择您的服务所处的空间。
2. 在服务实例页面中，选择您需要配置的UAA实例。
3. 选择配置服务实例选项。
4. 在UAA仪表板登录页面中，指定您的管理员客户端密码并点击登录。
5. 在UAA仪表板中，选择客户端管理选项卡。
客户端管理选项卡包括两部分，客户端和服务实例。服务实例部分显示您已经为您的服务创建的服务实例。
注：此处显示的服务实例是那些您使用您想要配置的UAA创建的实例。您使用其他UAA实例创建的服务实例不显示在此页面上。
6. 点击创建客户端按钮打开创建客户端窗体。
7. 在创建客户端窗体中指定以下值：
字段 说明
客户端ID 为您正在创建的OAuth2客户端指定一个名称。
客户端密码 指定密码。您要记住该密码，这一点非常重要。如果丢失，该密码无法找回。
确认客户端密码 重新输入客户端密码。
授权类型 从下面选择一个或多个授权类型：
o authorization_code
当您使用授权代码授权类型时，客户端将资源所有者定向至UAA，然后UAA反过来通过授权代码将资源所有者定向至客户端。
o client_credentials
当您使用客户端凭据授权类型时，UAA中的OAuth2端点接受客户端ID和客户端密码并提供访问令牌。
o password
当您使用资源所有者密码凭据授权类型时，UAA中的OAuth2端点接受用户名和密码并提供访问令牌。
o refresh_token
刷新令牌是获取访问令牌所用的凭据。您可以选择此选项以便从UAA获取刷新令牌。然后，当前的访问令牌变为无效或过期时，您可以使用刷新令牌从UAA获取一个新的访问令牌，或者获取具有相同或更窄范围的其他访问令牌。
o implicit
当您使用隐式授权类型时，UAA直接为客户端发布访问令牌，无需认证该客户端。这减少了获取访问令牌所需往返行程的数量。
关于不同授权类型的更多信息，请参见RFC 6749。

范围 范围是与一个OAuth客户端相关的许可，用于用户通过应用程序访问资源。用户许可用于授权类型 authorization_code, password 和 implicit。范围决定是否允许应用程序代表用户进行访问。
默认为管理员客户端分配所有需要的范围。对于新的客户端，管理员可以根据客户端要求选择要添加的范围。
关于可以分配的范围的完整列表，请参见UAA授权的范围。

权限 权限是指当一个应用程序或API使用其自有凭据访问一个资源时与OAuth客户端相关的许可，不涉及用户。许可用于授权类型 client_credentials。
默认为管理员客户端分配所有需要的权限。对于新的客户端，管理员可以根据客户端要求选择要添加的权限。
权限列表与范围列表相同。关于完整的列表，请参见UAA授权的范围。

自动批准的范围 为客户端指定可以自动批准的范围，无需资源所有者的明确批准。
重定向URI 指定一个重定向URI在登录后对客户端进行重定向。例如， http://example-app.com/welcome。
当您开始将UAA用作服务提供者时，该URI用于您的外部身份提供者。
访问令牌有效性 指定访问令牌失效时间，单位毫秒。
刷新令牌有效性 指定刷新令牌失效时间，单位毫秒。
允许的提供者 如果有的话，指定外部身份提供者的名称。如果您正在使用外部身份提供者，同时将UAA用作服务提供者，则该字段为必填。
使用UAAC创建一个OAuth2客户端
使用UAA命令行界面（UAAC）代替图形用户界面创建一个OAuth2客户端的可选程序。
您可以使用UAAC管理您的UAA实例。关于安装命令行界面的更多信息，请参见https://github.com/cloudfoundry/cf-uaac。
1. 将您的UAA实例指定为预定目标。
uaac target
是您的可信发布者的URL，例如， https://11fa0273-9e2a-37e2-9d06-2c95a1f4f5ea.predix-uaa.run.aws-usw02-pr.ice.predix.io。您可以在将您的UAA实例与一个应用程序绑定之后从VCAP_SERVICES环境变量中检索该URL。
2. 使用管理客户端登录。
uaac token client get admin
3. 在提示时指定管理客户端密码。
4. 使用以下命令创建OAuth2客户端：
uaac client add [client_name]–authorities “uaa.resource”–scope “openid”–autoapprove “openid”–authorized_grant_types [authorization_code|implicit|password|client_credentials|refresh_token]–redirect_uri [redirect_uri_1, redirect_uri_2, …]
关于UAA选项的更多信息，例如 scopes 和 authorized_grant_types，请参见https://github.com/GESoftware-CF/uaa/blob/master/docs/UAA-APIs.rst网页上的UAA文件。
更新OAuth2客户端
更新OAuth2客户端以添加每个平台服务的其他特定权限或范围的程序。
为了使您的应用程序能够访问平台服务，您的JSON网络令牌（JWT）必须包含该平台服务所需的范围。例如，访问控制服务需要的某些范围为 acs.policies.read acs.policies.write。关于一个服务所需范围的完整列表，请参见每个服务的相关部分。
OAuth2客户端使用一个授权请求一个访问令牌。OAuth2定义了四种授权类型。根据您使用的授权类型，您必须更新您的OAuth2客户端以生成所需的JWT。关于如何创建OAuth2客户端的更多信息，请参见创建OAuth2客户端。
当您创建一个UAA实例时，会自动为您创建一个管理员客户端，能够配置您的UAA实例。默认为管理员客户端分配所需的权限和范围。
如果您使用UAA仪表板创建其他客户端，客户端被默认创建为用于 client_credentials 授权类型。另外，会自动为客户端添加某些所需的权限和范围。您必须添加每个服务特定的其他权限或范围。
另外，管理员客户端默认没有被分配能够更改用户密码的权限。如果您需要更新或更改用户密码，您必须为您的管理员客户端添加 uaa.admin 权限。
以下程序显示了更新使用客户凭据授权的OAuth2客户端所需的步骤。
1. 在控制台视图中，选择您的服务所处的空间。
2. 在服务实例页面中，选择您需要配置的UAA实例。
3. 选择配置服务实例选项。
4. 在UAA仪表板登录页面中，指定您的管理员客户端密码并点击登录。
5. 在UAA仪表板中，选择客户端管理选项卡。
客户端管理选项卡包括两部分，客户端和服务实例。服务实例部分显示您已经为您的服务创建的服务实例。
注：此处显示的服务实例是那些您使用您想要配置的UAA创建的实例。您使用其他UAA实例创建的服务实例不显示在此页面上。
6. 在服务实例部分，在您需要更新客户端的服务中点击+ 授权客户端选项。
7. 从列表中选择一个现有客户端或选择添加一个新客户端选项。如果您选择添加一个新客户端，请遵循创建一个OAuth2客户端中的步骤。
8. 点击提交。
9. 在客户端管理选项卡中，点击与您在上一步中添加的客户端相对应的编辑图标。
10. 在编辑客户端窗体中指定以下值：
字段 说明
授权的授权类型 从下面选择一个或多个授权类型：
o client_credentials
当您使用客户端凭据授权类型时，UAA中的OAuth2端点接受客户端ID和客户端密码并提供访问令牌。客户端默认通过 client_credentials 授权创建。
o implicit
当您使用隐式授权类型时，UAA直接为客户端发布访问令牌，无需认证该客户端。这减少了获取访问令牌所需往返行程的数量。
o password
当您使用资源所有者密码凭据授权类型时，UAA中的OAuth2端点接受用户名和密码并提供访问令牌。
o authorization_code
当您使用授权代码授权类型时，客户端将资源所有者定向至UAA，然后UAA反过来通过授权代码将资源所有者定向至客户端。
当您使用这种授权类型时，也会默认分配一个 refresh_token 。
关于不同授权类型的更多信息，请参见RFC 6749。

范围 默认为客户端分配部分需要的范围。对于新的客户端，管理员可以根据所选的授权类型选择要添加的范围。
如果您选择 authorization_code, password 和 implicit 授权类型，您必须通过服务特定范围更新范围。
关于为每个服务添加的范围的完整列表，请参见平台服务所需的权限或范围。

权限 默认为客户端分配部分需要的权限。对于新的客户端，管理员可以根据所选的授权类型选择要添加的权限。
如果您选择 client_credentials 授权类型，您必须通过服务特定权限更新权限。
关于为每个服务添加的范围的完整列表，请参见平台服务所需的权限或范围。

自动批准的范围 为客户端指定可以自动批准的范围，无需资源所有者的明确批准。
重定向URI 指定一个重定向URI在登录后对客户端进行重定向。例如， http://example-app.com/welcome。
当您开始将UAA用作服务提供者时，该URI用于您的外部身份提供者。
访问令牌有效性 指定访问令牌失效时间，单位毫秒。
刷新令牌有效性 指定刷新令牌失效时间，单位毫秒。
允许的提供者 如果有的话，指定外部身份提供者的名称。如果您正在使用外部身份提供者，同时将UAA用作服务提供者，则该字段为必填。
资产服务所需的权限与范围
为了使应用程序能够访问资产服务，您的JSON网络令牌（JWT）必须包含以下范围： predix-asset.zones..user。
将一个应用程序与一个资产服务实例绑定
您必须将您的资产服务实例与您的应用程序绑定，以便为您在VCAP_SERVICES环境变量中的资产服务实例提供连接详细信息。Cloud Foundry运行时使用VCAP_SERVICES环境变量与部署的关于其环境的应用程序进行通信。
1. 将您的应用程序与新的资产服务实例绑定。
cf bind-service
实例与您的应用程序绑定，将返回以下消息：
Binding service to app in org cf_org_name / space cf_space_name as cf_username…OK TIP: Use 'cf restage' to ensure your env variable changes take effect
2. 验证绑定：
cf env
返回与以下消息类似的消息：
Getting env variables for app your_app_name in org cf_org_name / space cf_space_name as cf_user_name…OK {“VCAP_SERVICES”: {“predix-asset-dev”: [{“credentials”: {“instanceId”: “69c2bd61-4526-4379-9533-a2721fe83ba8”,”uri”: “http://predix-asset-rc.grc-apps.svc.ice.ge.com“,”zone”: {“http-header-name”: “Predix-Zone-Id”,”http-header-value”: “69c2bd61-4526-4379-9533-a2721fe83ba8”,”oauth-scope”: “predix-asset.zones.69c2bd61-4526-4379-9533-a2721fe83ba8.user”}},”label”: “predix-asset”,”name”: “testAsset”,”plan”: “”,”tags”: []}]}}
将资产模型数据添加到您的应用程序
客户端应用程序可以使用资产服务REST API端点访问资产数据。这些端点提供一个JSON接口，您可以将描述您的所有资产的数据提交至该接口。如果要使用这些API，您的应用程序需要发出HTTPS请求并分析响应。您可以使用任何网页开发语言访问API。
关于该API的更多信息，请参见API文件。
如果要为您的资产服务实例添加一系列资产：
1. 复制资产模型样本数据中的样本文件。
2. 从VCAP_SERVICES环境变量中检索资产实例详细信息：
o 资产实例 uri
o 进行REST调用所需的ID， instanceId。
3. 在一个REST客户端中：
a. 选择 POST 方法。
b. 输入从VCAP_SERVICES环境变量中获取的您的资产服务实例的URI。
c. 添加以下HTTP标头：
 Content-Type
输入值。application/json。
 Authorization
输入您从UAA接收的令牌，格式为 Bearer 。参见将一个应用程序与UAA实例绑定。
 Predix-Zone-Id
输入进行REST调用所需的ID，使用来自 instanceId 的值，该值来自VCAP_SERVICES环境变量。

d. 在您的请求的正文中输入格式正确的JSON。
如果要使用样本数据，可以从资产模型样本数据中复制JSON对象。

4. 使用资产服务API端点运行样本资产服务API请求。
活动概况：为了让国内开发者第一时间了解试用Predix 平台，及时跟踪了解国际工业互联网的最新技术，GE数字强调文字创新坊推出了Predix 开发者试用计划，并将提供Predix 的基础服务、微服务模块、开发工具等给有兴趣的开发者试用，试用期为3个月，这也是开发者进行工业化数字转型的第一步。需要注意的是该账号仅作开发评估目的使用，不能应用于任何商业用途，最终注册结果以邮件为准。并且GE保留对相关帐号申请、管理和使用的解释权。试用结束后，GE不保留任何开发者数据！
扫描下方二维码参与报名：