为 MindSphere 开发移动应用¶

本文描述如何为 MindSphere 开发移动应用。

MindSphere 的移动应用可以由多个组件组成，这些组件按以下方式分类：

先决条件¶

• MindSphere 开发者租户的用户账户。
  如果您还没有，请与您的租户管理员联系。相关说明，请参考为新用户提供访问。
• MindSphere 开发者角色， mdsp:core:Developer 或 mdsp:core:DeveloperAdmin。
• 如果您的应用拥有后端组件：该后端组件已经部署到 Cloud Foundry 或一些其他服务器。

在 Developer Cockpit 中注册移动应用¶

1. 从 Launchpad 中打开 Developer Cockpit 并选择 Dashboard 选项卡。
2. 单击**创建新的应用**。
3. 选择 Type Mobile。
4. 输入任意**显示名称**和版本号。
   • MindSphere 支持 Major.Minor.Patch 方案。
   • 版本必须以大于等于1的主设备号开头。
   • 版本在保存后不能被更改。
5. 选择托管您的移动应用的**基础设施**。
   • 带有后端组件的应用：选择 Cloud Foundry 或者自托管(作为部署)。
   • 不带有后端组件的应用：选择 none。
6. 输入**内部名称**，如果可用，它将作为 URL 的一部分用于寻址后端组件。初始创建后，**内部名称**不能更改！
7. 如果可用，添加后端组件。
8. 配置 Android 应用链接 和/或 通用链接 (可选)。
9. 单击**保存**。

可以使用以下模式的端点，在后端组件注册后进行访问：

```url tab="Template" https://gateway.{region}.{mindsphere_domain}/api/{internal_app_name}-{tenant_name}/{version}

```url tab="Example"
https://gateway.eu1.mindsphere.io/api/app_1-my_tenant/v1

更多有关注册 Developer Cockpit 应用的信息，请参考运行 Cloud Foundry-Hosted 应用或集成自托管应用到 MindSphere 或 Developer Cockpit 指南。

Android 应用链接和通用链接¶

Android 应用链接和通用链接(iOS)用于在登录 MindSphere 后自动将用户重定向回原生移动应用。它们是严格基于 HTTP 的 URLs，并且可以用于映射到多个应用。Android 和 iOS 都执行域验证，域验证需要以下指定的文件：

这些文件必须通过 HTTPS 承载，并带有内容类型 application/json 来提供服务。

```JSON tab="apple-app-site-association file"
{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "FM35W5TDQW.com.siemens.mdsp.MAECfBackend",
                "paths": [ "*" ]
            }
        ]
    }
}

更多信息请参考 Android 和 iOS 开发者指南。

访问 MindSphere APIs¶

与基于浏览器的应用相比，会话 cookie 不能用于移动应用。移动应用可以使用访问令牌作为 web 客户端访问 MindSphere APIS。

获取授权码¶

1. 构建您的移动应用的重定向 URI：

   ```url tab="Template" https://{provider_tenant}-{internal_app_name}-{provider_tenant}.{region}.{mindsphere_domain}/login

   ```url tab="Example"
   https://your_tenant-app_1-your_tenant.eu1.mindsphere.io/login
   

2. 使用重定向 URI 构建下面的 URL。这个 URL 将用户带到 MindSphere 登录屏幕。有关如何获取客户端 ID 的信息，请参考文档 Developer Cockpit 和 Operator Cockpit。

   ``url tab="Template" https://{provider_tenant}.piam.{region}.{mindsphere-domain}/oauth/authorize?login_hint={user_tenant}&response_type=code&client_id={client_id}}&redirect_uri={redirect_URI}&state={random-value}

   ```url tab="Example"
   https://your_tenant.piam.eu1.mindsphere.io/oauth/authorize?login_hint=user_tenant_1&response_type=code&client_id=mobile-client&redirect_uri=https://your_tenant-app_1-your_tenant.eu1.mindsphere.io/login
   

   state 参数

   授权协议接受一个 state 参数，该参数允许恢复应用的诱导状态。它用于避免 CSRF(Cross-site Request Forgery) 攻击。每个 state 值都是惟一的，并且与发起的身份验证请求相关联。您可以通过确认响应中的 state 与您的请求中的 state 匹配来防止攻击。

3. 调用准备好的 URL 来获得授权码。

在响应的 code 字符段中包含授权码。

获取访问令牌¶

获取访问令牌需要客户端 ID 和客户端密钥。只有当应用在 Developer 或 Operator Cockpit 中注册后，这些内容才会显示。

1. 用 Base64 格式编码客户端 ID 和客户端密钥的组合。

   • Combine client ID and client secret as shown below.

     {client_id}:{client_secret}
     

   • Encode the resulting string in Base64 format.

2. 发送 HTTP 请求到 OAuth Authorization Service：

   ```HTTP tab="Template" { POST https://{provider_tenant}.piam.{region}.{mindsphere-domain}/oauth/token Content-Type: application/x-www-form-urlencoded Authorization: Basic {credentials-in-Base64-format} grant_type: authorization_code redirect_uri: {app_link/universal_link} code: {authorization_code} tenant: {provider_tenant} }

   ```HTTP tab="Example"
   {
     POST https://your_tenant.piam.eu1.mindsphere.io/oauth/token
     Content-Type: application/x-www-form-urlencoded
     Authorization: Basic YmFzZTY0IGVuY29kZWQgc3RyaW5n
     grant_type: authorization_code
     redirect_uri: https://my_domain/.well-known
     code: code_123
     tenant: my_tenant
   }
   

响应包含一个访问令牌，用于访问 MindSphere APIs，如果可用，也可访问后端组件。此令牌有效期为30 分钟。

{
  "access_token": {JSON_web_token}
  "token_type": "bearer",
  "refresh_token": {JSON_web_token}
  "expires_in": 1799,
  "scope": {list_of_scopes>}
  "jti": {unique_value}
}

访问 MindSphere APIs¶

1. 像上面描述的一样请求访问令牌。

2. 如果可用，使用请求令牌调用您的后端组件（如果可用）或 MindSphere APIs。

   • 在请求头部的 Authorization 声明中将访问令牌作为承载令牌传递。
   • MindSphere APIs可从后端组件访问(如果可用)。
   • 后端组件可以重用授权头部来访问 MindSphere APIs。

   ```HTTP tab="Template without backend component" POST https://gateway.{region}.{mindsphere_domain}/api/{endpoint} HTTP1/1 Content-Type: application/json Authorization: Bearer {user_token}

   ```HTTP tab="Example"
   POST https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets HTTP1/1
   Content-Type: application/json
   Authorization: Bearer {user_token}
   

   ```HTTP tab="Template with backend component" POST https://gateway.{region}.{mindsphere_domain}/api/{internal_app_name}-{tenant_name}/v1 HTTP1/1 Content-Type: application/json Authorization: Bearer {user_token}

   ```HTTP tab="Example"
   POST https://gateway.eu1.mindsphere.io/api/app_1-your_tenant/v1/ HTTP1/1
   Content-Type: application/json
   Authorization: Bearer {user_token}
   

相关链接¶

• 运行 Cloud Foundry-Hosted 应用
• 集成自托管应用到 MindSphere