搜索​​​​

清除过滤器
文章
Michael Lei · 十二月 7, 2022

创建基于 FHIR 的表单

Intersystems IRIS for Health 对 FHIR 行业标准提供了出色的支持。主要特点是:1.FHIR 服务器2. FHIR数据库3. REST 和 ObjectScript API 用于 FHIR 资源(患者、问卷、疫苗等)的 CRUD 操作 本文演示了如何使用这些功能,并展示了用于创建和查看表单类型的 FHIR 资源的Angula前端。 第 1 步 - 使用 InterSystems IRIS for Health 部署您的 FHIR 服务器 要创建 FHIR 服务器,您必须将以下说明添加到 iris.script 文件中(来自:https://openexchange.intersystems.com/package/iris-fhir-template) zn "HSLIB" set namespace= "FHIRSERVER" Set appKey = "/fhir/r4" Set strategyClass = "HS.FHIRServer.Storage.Json.InteractionsStrategy" set metadataPackages = $lb ( "hl7.fhir.r4.core@4.0.1" ) set importdir= "/opt/irisapp/src" //Install a Foundation namespace and change to it Do ##class (HS.HC.Util.Installer).InstallFoundation(namespace) zn namespace // Install elements that are required for a FHIR-enabled namespace Do ##class (HS.FHIRServer.Installer).InstallNamespace() // Install an instance of a FHIR Service into the current namespace Do ##class (HS.FHIRServer.Installer).InstallInstance(appKey, strategyClass, metadataPackages) // Configure FHIR Service instance to accept unauthenticated requests set strategy = ##class (HS.FHIRServer.API.InteractionsStrategy).GetStrategyForEndpoint(appKey) set config = strategy.GetServiceConfigData() set config.DebugMode = 4 do strategy.SaveServiceConfigData(config) zw ##class (HS.FHIRServer.Tools.DataLoader).SubmitResourceFiles( "/opt/irisapp/fhirdata/" , "FHIRServer" , appKey) do $System .OBJ.LoadDir( "/opt/irisapp/src" , "ck" ,, 1 ) zn "%SYS" Do ##class (Security.Users).UnExpireUserPasswords( "*" ) zn "FHIRSERVER" zpm "load /opt/irisapp/ -v" : 1 : 1 //zpm "install fhir-portal" halt 使用实用程序类 HS.FHIRServer.Installer,您可以创建 FHIR 服务器。 第 2 步 - 使用 FHIR REST 或 ObjectScript API 读取、更新、删除和查找 FHIR 数据 我喜欢使用 ObjectScript 类 HS.FHIRServer.Service 来执行所有 CRUD 操作。 要从资源类型(表单)中获取所有 FHIR 数据: /// Retreive all the records of questionnaire ClassMethod GetAllQuestionnaire() As %Status { set tSC = $$$OK Set %response.ContentType = ..#CONTENTTYPEJSON Set %response.Headers ( "Access-Control-Allow-Origin" )= "*" Try { set fhirService = ##class (HS.FHIRServer.Service).EnsureInstance(..#URL) set request = ##class (HS.FHIRServer.API.Data.Request). %New () set request.RequestPath = "/Questionnaire/" set request.RequestMethod = "GET" do fhirService.DispatchRequest(request, .pResponse) set json = pResponse.Json set resp = [] set iter = json.entry. %GetIterator () while iter. %GetNext (.key, .value) { do resp. %Push (value.resource) } write resp. %ToJSON () } Catch Err { set tSC = 1 set message = {} set message.type= "ERROR" set message.details = "Error on get all questionnairies" } Quit tSC } 要从 FHIR 数据存储库中获取特定数据项(调查表): /// Retreive a questionnaire by id ClassMethod GetQuestionnaire(id As %String ) As %Status { set tSC = $$$OK Set %response.ContentType = ..#CONTENTTYPEJSON Set %response.Headers ( "Access-Control-Allow-Origin" )= "*" Try { set fhirService = ##class (HS.FHIRServer.Service).EnsureInstance(..#URL) set request = ##class (HS.FHIRServer.API.Data.Request). %New () set request.RequestPath = "/Questionnaire/" _id set request.RequestMethod = "GET" do fhirService.DispatchRequest(request, .pResponse) write pResponse.Json. %ToJSON () } Catch Err { set tSC = 1 set message = {} set message.type= "ERROR" set message.details = "Error on get the questionnaire" } Quit tSC } 要创建新的 FHIR 资源事件(新的调查表): /// Create questionnaire ClassMethod CreateQuestionnaire() As %Status { set tSC = $$$OK Set %response.ContentType = ..#CONTENTTYPEJSON Set %response.Headers ( "Access-Control-Allow-Origin" )= "*" Try { set fhirService = ##class (HS.FHIRServer.Service).EnsureInstance(..#URL) set request = ##class (HS.FHIRServer.API.Data.Request). %New () set request.RequestPath = "/Questionnaire/" set request.RequestMethod = "POST" set data = {}. %FromJSON ( %request.Content ) set data.resourceType = "Questionnaire" set request.Json = data do fhirService.DispatchRequest(request, .response) write response.Json. %ToJSON () } Catch Err { set tSC = 1 set message = {} set message.type= "ERROR" set message.details = "Error on create questionnaire" } Return tSC } 要更新 FHIR 资源(表单): /// Update a questionnaire ClassMethod UpdateQuestionnaire(id As %String ) As %Status { set tSC = $$$OK Set %response.ContentType = ..#CONTENTTYPEJSON Set %response.Headers ( "Access-Control-Allow-Origin" )= "*" Try { set fhirService = ##class (HS.FHIRServer.Service).EnsureInstance(..#URL) set request = ##class (HS.FHIRServer.API.Data.Request). %New () set request.RequestPath = "/Questionnaire/" _id set request.RequestMethod = "PUT" set data = {}. %FromJSON ( %request.Content ) set data.resourceType = "Questionnaire" set request.Json = data do fhirService.DispatchRequest(request, .response) write response.Json. %ToJSON () } Catch Err { set tSC = 1 set message = {} set message.type= "ERROR" set message.details = "Error on update questionnaire" } Return tSC } 要删除 FHIR 资源事件(表单): /// Delete a questionnaire by id ClassMethod DeleteQuestionnaire(id As %String ) As %Status { set tSC = $$$OK Set %response.ContentType = ..#CONTENTTYPEJSON Set %response.Headers ( "Access-Control-Allow-Origin" )= "*" Try { set fhirService = ##class (HS.FHIRServer.Service).EnsureInstance(..#URL) set request = ##class (HS.FHIRServer.API.Data.Request). %New () set request.RequestPath = "/Questionnaire/" _id set request.RequestMethod = "DELETE" do fhirService.DispatchRequest(request, .pResponse) } Catch Err { set tSC = 1 set message = {} set message.type= "ERROR" set message.details = "Error on delete the questionnaire" } Quit tSC } 如您所见,您想要创建使用 POST,更新使用 PUT,删除使用 DELETE,查询使用 GET 动词。 第 3 步 - 创建 Angular 客户端以使用您的 FHIR 服务器应用程序 我使用 PrimeNG 创建了一个角度应用程序并安装了包 npm install --save @types/fhir。此包具有映射到 TypeScript 的所有 FHIR 类型。 Angular控制器类: import { Component, OnInit, ViewEncapsulation } from '@angular/core' ; import { ActivatedRoute, Router } from '@angular/router' ; import { Period, Questionnaire } from 'fhir/r4' ; import { ConfirmationService, MessageService, SelectItem } from 'primeng/api' ; import { QuestionnaireService } from './questionnaireservice' ; const QUESTIONNAIREID = 'questionnaireId' ; @Component({ selector: 'app-questionnaire', templateUrl: './questionnaire.component.html', providers: [MessageService, ConfirmationService], styleUrls: ['./questionnaire.component.css'], encapsulation: ViewEncapsulation.None }) export class QuestionnaireComponent implements OnInit { public questionnaire: Questionnaire ; public questionnairies: Questionnaire[] ; public selectedQuestionnaire: Questionnaire ; public questionnaireId: string ; public sub: any ; public publicationStatusList: SelectItem[] ; constructor( private questionnaireService: QuestionnaireService, private router: Router, private route: ActivatedRoute, private confirmationService: ConfirmationService, private messageService: MessageService){ this.publicationStatusList = [ {label: 'Draft', value: 'draft'}, {label: 'Active', value: 'active'}, {label: 'Retired', value: 'retired'}, {label: 'Unknown', value: 'unknown'} ] } ngOnInit() { this.reset() ; this.listQuestionnaires() ; this.sub = this.route.params.subscribe(params => { this.questionnaireId = String(+params[QUESTIONNAIREID]) ; if (!Number.isNaN(this.questionnaireId)) { this.loadQuestionnaire(this.questionnaireId) ; } }) ; } private loadQuestionnaire(questionnaireId) { this.questionnaireService.load(questionnaireId).subscribe(response => { this.questionnaire = response ; this.selectedQuestionnaire = this.questionnaire ; if (!response.effectivePeriod) { this.questionnaire.effectivePeriod = <Period>{} ; } }, error => { console.log(error) ; this.messageService.add({ severity: 'error', summary: 'Error', detail: 'Error on load questionnaire.' }) ; }) ; } public loadQuestions() { if (this.questionnaire && this.questionnaire.id) { this.router.navigate(['/question', this.questionnaire.id]) ; } else { this.messageService.add({ severity: 'warn', summary: 'Warning', detail: 'Choose a questionnaire.' }) ; } } private listQuestionnaires() { this.questionnaireService.list().subscribe(response => { this.questionnairies = response ; this.reset() ; }, error => { console.log(error) ; this.messageService.add({ severity: 'error', summary: 'Error', detail: 'Error on load the questionnaries.' }) ; }) ; } public onChangeQuestionnaire() { if (this.selectedQuestionnaire && !this.selectedQuestionnaire.id) { this.messageService.add({ severity: 'warn', summary: 'Warning', detail: 'Select a questionnaire.' }) ; } else { if (this.selectedQuestionnaire && this.selectedQuestionnaire.id) { this.loadQuestionnaire(this.selectedQuestionnaire.id) ; } } } public reset() { this.questionnaire = <Questionnaire>{} ; this.questionnaire.effectivePeriod = <Period>{} ; } public save() { if (this.questionnaire.id && this.questionnaire.id != "" ) { this.questionnaireService.update(this.questionnaire).subscribe( (resp) => { this.messageService.add({ severity: 'success', summary: 'Success', detail: 'Questionnaire saved.' }) ; this.listQuestionnaires() this.loadQuestionnaire(this.questionnaire.id) ; }, error => { console.log(error) ; this.messageService.add({ severity: 'error', summary: 'Error', detail: 'Error on save the questionnaire.' }) ; } ) ; } else { this.questionnaireService.save(this.questionnaire).subscribe( (resp) => { this.messageService.add({ severity: 'success', summary: 'Success', detail: 'Questionnaire saved.' }) ; this.listQuestionnaires() this.loadQuestionnaire(resp.id) ; }, error => { console.log(error) ; this.messageService.add({ severity: 'error', summary: 'Error', detail: 'Error on save the questionnaire.' }) ; } ) ; } } public delete(id: string) { if (!this.questionnaire || !this.questionnaire.id) { this.messageService.add({ severity: 'warn', summary: 'Warning', detail: 'Select a questionnaire.' }) ; } else { this.confirmationService.confirm({ message: ' Do you confirm?', accept: () => { this.questionnaireService.delete(id).subscribe( () => { this.messageService.add({ severity: 'success', summary: 'Success', detail: 'Questionnaire deleted.' }) ; this.listQuestionnaires() ; this.reset() ; }, error => { console.log(error) ; this.messageService.add({ severity: 'error', summary: 'Error', detail: 'Error on delete questionnaire.' }) ; } ) ; } }) ; } } } Angular HTML 文件 <p-toast [style]= "{marginTop: '80px', width: '320px'}" ></p-toast> <p-card> <div class = "p-fluid p-formgrid grid" > <div class = "field col-12 lg:col-12 md:col-12" > <p-dropdown id= "dropquestions1" [options]= "questionnairies" [(ngModel)]= "selectedQuestionnaire" (onChange)= "onChangeQuestionnaire()" placeholder= "Select a Questionnaire" optionLabel= "title" [filter]= "true" [showClear]= "true" ></p-dropdown> </div> </div> <p-tabView> <p-tabPanel leftIcon= "fa fa-question" header= "Basic Data" > <div class = "p-fluid p-formgrid grid" > <div class = "field col-3 lg:col-3 md:col-12" > <label for = "txtname" >Name</label> <input class = "inputfield w-full" id= "txtname" required type= "text" [(ngModel)]= "questionnaire.name" pInputText placeholder= "Name" > </div> <div class = "field col-7 lg:col-7 md:col-12" > <label for = "txttitle" >Title</label> <input class = "inputfield w-full" id= "txttitle" required type= "text" [(ngModel)]= "questionnaire.title" pInputText placeholder= "Title" > </div> <div class = "field col-2 lg:col-2 md:col-12" > <label for = "txtdate" >Date</label> <p-inputMask id= "txtdate" mask= "9999-99-99" [(ngModel)]= "questionnaire.date" placeholder= "9999-99-99" slotChar= "yyyy-mm-dd" ></p-inputMask> </div> <div class = "field col-2 lg:col-2 md:col-12" > <label for = "txtstatus" >Status</label> <p-dropdown [options]= "publicationStatusList" [(ngModel)]= "questionnaire.status" ></p-dropdown> </div> <div class = "field col-3 lg:col-3 md:col-12" > <label for = "txtpublisher" >Publisher</label> <input class = "inputfield w-full" id= "txtpublisher" required type= "text" [(ngModel)]= "questionnaire.publisher" pInputText placeholder= "Publisher" > </div> <div class = "field col-2 lg:col-2 md:col-12" > <label for = "txtstartperiod" >Start Period</label> <p-inputMask id= "txtstartperiod" mask= "9999-99-99" [(ngModel)]= "questionnaire.effectivePeriod.start" placeholder= "9999-99-99" slotChar= "yyyy-mm-dd" ></p-inputMask> </div> <div class = "field col-2 lg:col-2 md:col-12" > <label for = "txtendperiod" >End Period</label> <p-inputMask id= "txtendperiod" mask= "9999-99-99" [(ngModel)]= "questionnaire.effectivePeriod.end" placeholder= "9999-99-99" slotChar= "yyyy-mm-dd" ></p-inputMask> </div> <div class = "field col-12 lg:col-12 md:col-12" > <label for = "txtcontent" >Description</label> <p-editor [(ngModel)]= "questionnaire.description" [style]= "{'height':'100px'}" ></p-editor> </div> </div> <div class = "grid justify-content-end" > <button pButton pRipple type= "button" label= "New Record" (click)= "reset()" class = "p-button-rounded p-button-success mr-2 mb-2" ></button> <button pButton pRipple type= "button" label= "Save" (click)= "save()" class = "p-button-rounded p-button-info mr-2 mb-2" ></button> <button pButton pRipple type= "button" label= "Delete" (click)= "delete(questionnaire.id)" class = "p-button-rounded p-button-danger mr-2 mb-2" ></button> <button pButton pRipple type= "button" label= "Questions" (click)= "loadQuestions()" class = "p-button-rounded p-button-info mr-2 mb-2" ></button> </div> </p-tabPanel> </p-tabView> </p-card> <p-confirmDialog #cd header= "Atenção" icon= "pi pi-exclamation-triangle" > <p-footer> <button type= "button" pButton icon= "pi pi-times" label= "Não" (click)= "cd.reject()" ></button> <button type= "button" pButton icon= "pi pi-check" label= "Sim" (click)= "cd.accept()" ></button> </p-footer> </p-confirmDialog> 角度服务类 import { Injectable } from '@angular/core' ; import { HttpClient, HttpHeaders } from '@angular/common/http' ; import { Observable } from 'rxjs' ; import { environment } from 'src/environments/environment' ; import { take } from 'rxjs/operators' ; import { Questionnaire } from 'fhir/r4' ; @Injectable({ providedIn: 'root' }) export class QuestionnaireService { private url = environment.host2 + 'questionnaire' ; constructor(private http: HttpClient) { } public save(Questionnaire: Questionnaire): Observable<Questionnaire> { return this.http.post<Questionnaire>(this.url, Questionnaire).pipe(take( 1 )) ; } public update(Questionnaire: Questionnaire): Observable<Questionnaire> { return this.http.put<Questionnaire>(`${this.url}/${Questionnaire.id}`, Questionnaire).pipe(take( 1 )) ; } public load(id: string): Observable<Questionnaire> { return this.http.get<Questionnaire>(`${this.url}/${id}`).pipe(take( 1 )) ; } public delete(id: string): Observable<any> { return this.http.delete(`${this.url}/${id}`).pipe(take( 1 )) ; } public list(): Observable<Questionnaire[]> { return this.http.get<Questionnaire[]>(this.url).pipe(take( 1 )) ; } } 第 4 步 - 实际应用 1. 转到 https://openexchange.intersystems.com/package/FHIR-Questionnaires 应用程序。 2. clone/git pull repo 到任何本地目录 $ git clone https://github.com/yurimarx/fhir-questions.git 3、在该目录下打开终端,运行: $ docker-compose up -d 4.打开网络应用程序: http://localhost:52773/fhirquestions/index.html 截图:
文章
Lilian Huang · 九月 7, 2023

Docker 简介 - 第 2 部分(Docker Compose、Docker File、Docker Volume)

您好!社区的各位老师, 在我的上一篇文章中,我们学习了以下主题: 什么是 Docker? Docker 的一些好处 Docker 是如何工作的? Docker 镜像 Docker容器 Docker 镜像存储库 InterSystems 的 Docker 镜像存储库 Docker安装 Docker 基本命令 使用 Docker 运行 IRIS 社区版 Docker 桌面图形用户界面 在本文中,我们将讨论以下主题: 使用 Docker Compose 文件( YAML 文件) Docker 文件的使用(用于构建 Docker 镜像) Docker 卷的使用 那么让我们开始吧。 1.使用Docker Compose文件( YAML文件) Docker Compose 是一款旨在帮助定义和共享多容器应用程序的工具。使用 Compose,我们可以创建一个 YAML 文件来定义服务,并且通过单个命令,我们可以启动或拆除所有内容。 使用 Compose 的一大优势是能够在文件中定义应用程序堆栈并将其保存在项目存储库的根目录中。您还可以让其他人轻松地为您的项目做出贡献。 他们只需要克隆您的存储库并启动撰写应用程序。 在我的上一篇文章中,我们使用下面提到的命令来创建并启动带有 InterSystems 社区镜像的容器: docker run -d -p 52773:52773 intersystemsdc/iris-community 此时,让我们修改此命令并添加容器名称、映射更多端口并设置重新启动选项: docker run -d -p 52773:52773 -p 53773:53773 -p 1972:1972 --name iris --restart=always intersystemsdc/iris-community 让我为您分解一下上述命令: # docker run command to create and start the container docker run # -d -an option used to start container in deattach mode -d # -p -an option is used to map the ports -p 52773:52773 -p 53773:53773 -p 1972:1972 # name of the container --name iris # set the restart option to always --restart=always # base image intersystemsdc/iris-community 创建撰写文件 在根文件夹中,创建一个名为-----100-----的文件,并写入上述命令,如下所示: #specify docker-compose version version: '3.6' #services/container details services: #Name of the container iris: #Base Image image: intersystemsdc/iris-community #set restart option restart: always #port mapping ports: - 55036 :1972 - 55037 :52773 - 53773 :53773 docker run 命令和 docker-compose 文件的映射如下所示:Docker-compose 文件快照如下所示: 为了运行 docker-compose 文件代码,我们将使用 docker-compose up 命令: docker-compose up -d -----101----- 或 -----102-----:在后台运行命令并将控制返回到终端的选项。 容器已启动。让我们运行“docker ps”命令来列出正在运行的容器 正如您所看到的,我们使用 docker-compose 文件得到了相同的结果。 创建并启动多个容器 在 docker-compose 的帮助下,我们不仅可以运行多个容器,还可以组织并向其添加更多命令。 例如,在下面的 docker-compose 文件中,我们运行 MongoDB 容器和 iris 容器: #specify docker-compose version version: '3.6' #services/container details services: #Name of the container iris: #Base Image image: intersystemsdc/iris-community #set restart option restart: always #port mapping ports: - 55036:1972 - 55037:52773 - 53773:53773 #start MongoDB container mongodb: image: mongo ports: - 27017:27017 让我们运行 docker-compose up 命令 MongoDB 和 iris 容器现已创建并启动。 2.Docker 文件 Docker可以通过读取-----103-----的指令来自动构建镜像。 -----103----- 是一个文本文档,其中包含用户可以在命令行上调用来组装图像的所有命令。 所以,我们的第一个问题很简单。什么是 Dockerfile? Docker 使用它来构建镜像本身。 Dockerfile 本质上是如何创建镜像的构建指令。 与简单存储二进制映像相比,Dockerfile 的优点是自动构建将确保您拥有可用的最新版本。从安全角度来看这是一件好事,因为您希望确保没有安装任何易受攻击的软件。 常用 Docker 文件命令 您可以在下面找到一些最常用的 docker 命令。请注意,所有 docker 命令都必须大写字母。 从 第一个是 FROM 命令,它告诉您映像基于什么。正是这种多层方法使得 Docker 如此高效和强大。在本例中,使用了 iris-community Docker 映像,它再次引用 Dockerfile 来自动化构建过程。 FROM intersystemsdc/iris-community 工作目录 该命令用于设置一个工作目录,我们将在其中复制文件。例如,下面提到的命令将设置 /opt/irisbuild 作为工作目录: WORKDIR /opt/irisbuild 复制 COPY 命令就像听起来一样简单。它可以将文件复制到容器中。通常,我们复制自定义配置文件、应用程序源文件、数据文件等。 #coping Installer.cls to a root of workdir. Don't miss the dot, here. COPY Installer.cls . #copy source files from src folder to src folder in workdir in the docker container. COPY src src #copy source files from data/fhir folder to fhirdata folder in the docker container. COPY data/fhir fhirdata 环境电压 这会设置环境变量,这些变量可以在 Dockerfile 及其调用的任何脚本中使用。-----105-----指令将环境变量-----106-----定义为值-----107----- ENV USER_ID "SYSTEM" ENV USER_PASSWORD "MANAGER" 跑步 -----108-----命令用于在镜像构建过程中执行命令。 #here we give the rights to irisowner user and group which are run IRIS. RUN chown ${ISC_PACKAGE_MGRUSER} : ${ISC_PACKAGE_IRISGROUP} /opt/irisapp #start IRIS and run script in iris.script file RUN iris start IRIS \ && iris session IRIS < /tmp/iris.script 用户 默认情况下,容器以 root 身份运行,这使它们能够完全控制主机系统。随着容器技术的成熟,可能会出现更安全的默认选项。目前,要求 root 对其他人来说是危险的,并且可能不适用于所有环境。您的映像应使用 -----109----- 指令来指定容器运行的非 root用户。如果您的软件没有创建自己的用户,您可以在 Dockerfile 中创建用户和组。 #here we switch user to a root to create a folder and copy files in docker. USER root WORKDIR /opt/irisapp #switching user from root to irisowner, to copy files USER irisowner COPY src src 更多细节请阅读Docker官方文档 3.Docker卷 Docker卷是一个完全由Docker管理的独立文件系统。它作为标准文件或目录存在于数据保存的主机上。 使用 Docker 卷的目的是将数据保留在容器外部,以便可用于备份或共享。 Docker 卷依赖于 Docker 的文件系统,是 Docker 容器和服务保存数据的首选方法。当容器启动时,Docker 会加载只读镜像层,在镜像堆栈顶部添加读写层,并将卷挂载到容器文件系统上。 我们使用 -----110----- 或 -----111----- 标志来允许我们将本地文件挂载到容器中。 卷是保存 Docker 容器生成和使用的数据的首选机制。虽然绑定挂载取决于主机的目录结构和操作系统,但卷完全由 Docker 管理。与绑定挂载相比,卷有几个优点: 卷比绑定安装更容易备份或迁移。 您可以使用 Docker CLI 命令或 Docker API 管理卷。 卷适用于 Linux 和 Windows 容器。 卷可以在多个容器之间更安全地共享。 卷驱动程序允许您将卷存储在远程主机或云提供商上,以加密卷的内容或添加其他功能。 新卷的内容可以由容器预先填充。 Docker Desktop 上的卷比 Mac 和 Windows 主机上的绑定挂载具有更高的性能。 此外,卷通常是比将数据保留在容器的可写层中更好的选择,因为卷在使用时不会增加容器的大小。此外,卷的内容存在于给定容器的生命周期之外。 我们可以在 docker-compose 文件的 services 部分下提及卷。 #specify docker-compose version version: '3.6' #services/container details services: #Name of the container iris: #Base Image image: intersystemsdc/iris-community #set restart option restart: always #port mapping ports: - 55036 :1972 - 55037 :52773 - 53773 :53773 #create a volume volumes: - ./:/irisdev/app 我们已经创建了 irisdev/app 卷。 概括 Docker 是一个功能强大的工具,允许开发人员和 IT 团队在容器化环境中创建、部署和运行应用程序。通过提供可移植性、一致性、可扩展性、资源效率和安全性,Docker 可以轻松地跨不同环境和基础设施部署应用程序。随着容器化的日益普及,Docker正在成为现代软件开发和部署的重要工具。在本文中,我们学习了如何使用 Docker compose(一个 YAML 文件,指定应用程序中每个容器的配置选项)、Docker 文件(用于构建 Docker 镜像)和 Docker 卷(一种用于共享数据的持久数据存储机制) Docker 容器和主机之间的数据。) 感谢您的阅读!
文章
Michael Lei · 七月 6, 2021

精华文章--虚拟化大型数据库 - VMware CPU 容量规划

供应商或内部团队要求说明如何为 VMware vSphere 上运行的_大型生产数据库_进行 CPU 容量规划。 总的来说,在调整大型生产数据库的 CPU 规模时,有几个简单的最佳做法可以遵循: - 为每个物理 CPU 核心规划一个 vCPU。 - 考虑 NUMA 并按理想情况调整虚拟机规模,以使 CPU 和内存对于 NUMA 节点是本地的。 - 合理调整虚拟机规模。 仅在需要时才添加 vCPU。 通常,这会引出几个常见问题: - 由于使用超线程技术,VMware 创建的虚拟机的 CPU 数量可以是物理 CPU 数量的两倍。 那不就是双倍容量吗? 创建的虚拟机不应该有尽可能多的 CPU 吗? - 什么是 NUMA 节点? 我应该在意 NUMA 吗? - 虚拟机应该合理调整规模,但我如何知道什么时候合理? 我以下面的示例回答这些问题。 但也要记住,最佳做法并不是一成不变的。 有时需要做出妥协。 例如,大型生产数据库虚拟机很可能不适合 NUMA 节点,但我们会看到,其实是没问题的。 最佳做法是指必须针对应用程序和环境进行评估和验证的准则。 虽然本文中的示例是在 InterSystems 数据平台上运行的数据库,但概念和规则通常适用于任何大型(怪兽)虚拟机的容量和性能规划。 有关虚拟化最佳做法以及有关性能和容量规划的更多帖子,请参见 [InterSystems 数据平台和性能系列的其他帖子列表](https://cn.community.intersystems.com/post/intersystems-数据平台的容量规划和性能系列文章)。 # 怪兽虚拟机 本帖主要是关于部署_怪兽虚拟机_,有时也称为 _Wide 虚拟机_。 高事务数据库的 CPU 资源要求意味着它们通常部署在怪兽虚拟机上。 > 怪兽虚拟机是指虚拟 CPU 或内存多于物理 NUMA 节点的虚拟机。 # CPU 架构和 NUMA 当前的英特尔处理器架构采用非统一内存架构 (NUMA)。 例如,本帖中用来运行测试的服务器有: - 两个 CPU 插槽,每个插槽一个 12 核处理器(英特尔 E5-2680 v3)。 - 256 GB 内存(16 条 16GB RDIMM) 每个 12 核处理器都有自己的本地内存(128GB RDIMM 及本地高速缓存),还可以访问同一主机中其他处理器上的内存。 每个由 CPU、CPU 高速缓存和 128GB RDIMM 内存组成的 12 核套装都是一个 NUMA 节点。 为了访问其他处理器上的内存,NUMA 节点通过快速互连来连接。 处理器上运行的进程访问本地 RDIMM 和缓存内存的延迟比跨互连访问其他处理器上的远程内存的延迟要低。 跨互连访问会增加延迟,因此性能不一致。 同样的设计也适用于具有两个以上插槽的服务器。 一台四插槽英特尔服务器有四个 NUMA 节点。 ESXi 了解物理 NUMA,ESXi CPU 调度器设计为优化 NUMA 系统的性能。 ESXi 使性能最大化的方法之一是在物理 NUMA 节点上创建数据本地性。 在我们的示例中,如果虚拟机有 12 个 vCPU,并且内存不到 128GB,ESXi 将分配该虚拟机在一个物理 NUMA 节点上运行。 这就形成了规则: > 如果可能,将虚拟机规模调整为使 CPU 和内存对于 NUMA 节点是本地的。 如果需要比 NUMA 节点规模大的怪兽虚拟机也没有问题,ESXi 可以很好地自动计算和管理要求。 例如,ESXi 将创建能够智能调度到物理 NUMA 节点上的虚拟 NUMA 节点 (vNUMA),以获得最佳性能。 vNUMA 结构对操作系统公开。 例如,如果您有一台具有两个 12 核处理器的主机服务器和一个具有 16 个 vCPU 的虚拟机,ESXi 可能会使用每个处理器上的 8 个物理核心来调度虚拟机 vCPU,操作系统(Linux 或 Windows)将看到两个 NUMA 节点。 同样重要的是,应合理调整虚拟机的规模,并且分配的资源不要超过所需的资源,否则会导致资源浪费和性能损失。 除了有助于调整 NUMA 的规模,具有高(但安全的)CPU 利用率的 12 vCPU 虚拟机比具有中低 CPU 利用率的 24 vCPU 虚拟机更高效、性能更好,特别是该主机上还有其他虚拟机需要调度并且争用资源时。 这也再次强化了该规则: > 合理调整虚拟机规模。 __注意:__英特尔和 AMD 的 NUMA 实现有区别。 AMD 每个处理器有多个 NUMA 节点。 我已经有一段时间没有在客户服务器中看到 AMD 处理器了,但是如果你有这些处理器,请检查 NUMA 布局,作为规划的一部分。 ## Wide 虚拟机和授权 为实现最佳 NUMA 调度,请配置 Wide 虚拟机; 2017 年 6 月更正:按每个插槽 1 个 vCPU 配置虚拟机。 例如,默认情况下,一个具有 24 个 vCPU 的虚拟机应配置为 24 个 CPU 插槽,每个插槽一个核心。 > 遵守 VMware 最佳做法规则。 请参见 [VMware 博客上的这篇文章以查看示例。 ](https://blogs.vmware.com/performance/2017/03/virtual-machine-vcpu-and-vnuma-rightsizing-rules-of-thumb.html) 该 VMware 博客文章进行了详细介绍,但是作者 Mark Achtemichuk 建议遵循以下经验法则: - 虽然有许多高级 vNUMA 设置,但只有极少数情况下需要更改其默认值。 - 总是将虚拟机 vCPU 数配置为反映每插槽核心数,直到超过单个物理 NUMA 节点的物理核心数。 - 当需要配置的 vCPU 数量超过 NUMA 节点中的物理核心数量时,将 vCPU 均匀分配到最少数量的 NUMA 节点上。 - 当虚拟机规模超过物理 NUMA 节点时,不要分配奇数数量的 vCPU。 - 不要启用 vCPU 热添加,除非您不介意禁用 vNUMA。 - 不要创建规模大于主机物理核心总数的虚拟机。 Caché 授权以核心数为准,因此这不是问题,但是对于除 Caché 以外的软件或数据库,指定虚拟机有 24 个插槽可能会对软件授权产生影响,因此必须与供应商核实。 # 超线程和 CPU 调度器 超线程 (HT) 经常在讨论中出现,我听过“超线程使 CPU 核心数量翻倍”。 这在物理层面上显然是不可能的,物理核心有多少就是多少。 超线程应该被启用,并会提高系统性能。 预计应用程序性能可能会提高 20% 或更多,但实际数字取决于应用程序和工作负载。 但肯定不会翻倍。 正如我在 [VMware 最佳实践](https://cn.community.intersystems.com/post/intersystems-数据平台和性能-–-第-9-篇-intersystems-iris-vmware-最佳实践指南)中所述,_调整大型生产数据库虚拟机规模_的一个很好的起点是假定 vCPU 拥有服务器上完整的物理核心专用资源 — 在进行容量规划时基本忽略超线程。 例如: > 对于一台 24 核主机服务器,可规划总共多达 24 个 vCPU 的生产数据库虚拟机,且可能还有余量。 在您花时间监测应用程序、操作系统和 VMware 在峰值处理期间的性能后,您可以决定是否进行更高度的虚拟机整合。 在最佳做法帖子中,我将规则表述为: > 一个物理 CPU(包括超线程)= 一个 vCPU(包括超线程)。 ## 为什么超线程不会使 CPU 翻倍 英特尔至强处理器上的超线程是在一个物理核心上创建两个_逻辑_ CPU 的方法。 操作系统可以有效地针对两个逻辑处理器进行调度 — 如果一个逻辑处理器上的进程或线程正在等待,例如等待 IO,则物理 CPU 资源可以被另一个逻辑处理器使用。 在任何时间点都只能有一个逻辑处理器运行,因此虽然物理核心得到了更有效的利用,但_性能并没有翻倍_。 在主机 BIOS 中启用超线程后,当创建虚拟机时,可以为每个超线程逻辑处理器配置一个 vCPU。 例如,在一台启用了超线程的物理 24 核服务器上,可以创建具有多达 48 个 vCPU 的虚拟机。 ESXi CPU 调度器将通过首先在独立的物理核心上运行虚拟机进程来优化处理(同时仍然考虑 NUMA)。 在以后的帖子中,我将探讨在怪兽数据库虚拟机上分配比物理核心数更多的 vCPU 是否有助于扩展。 ### 协同停止和 CPU 调度 在监测主机和应用程序性能后,您可以决定是否让主机 CPU 资源过载。 这是否是一个好主意在很大程度上取决于应用程序和工作负载。 了解调度器和要监测的关键指标有助于确保没有使主机资源过载。 我有时听说,要让虚拟机正常运行,空闲逻辑 CPU 的数量必须与虚拟机中的 vCPU 数量相同。 例如,一个 12 vCPU 虚拟机必须“等待”12 个逻辑 CPU“可用”,才能继续执行。 不过应该注意,ESXi 在版本 3 之后就不是这样了。 ESXi 对 CPU 使用宽松的协同调度,以提高应用程序性能。 由于多个协作线程或进程经常相互同步,不一起调度它们可能会增加操作的延迟。 例如,在自旋循环中,一个线程等待被另一个线程调度。 为了获得最佳性能,ESXi 尝试将尽可能多的同级 vCPU 一起调度。 但是,当有多个虚拟机在整合环境中争用 CPU 资源时,CPU 调度器可以灵活地调度 vCPU。 如果一些 vCPU 的进展比同级 vCPU 领先太多(这个时间差称为偏移),领先的 vCPU 将决定是否停止自身(协同停止)。 请注意,协同停止(或协同启动)的是 vCPU,不是整个虚拟机。 这种机制即使在资源有些过载的情况下也非常有效,但正如您所预期,CPU 资源过载太多将不可避免地影响性能。 我在后面的示例 2 中展示了一个过载和协同停止的例子。 记住,这不是虚拟机之间全力争夺 CPU 资源的竞赛;ESXi CPU 调度器的工作是确保 CPU 共享、保留和限制等策略被遵守,同时最大限度地提高 CPU 利用率,并确保公平性、吞吐量、响应速度和可伸缩性。 关于使用保留和共享来确定生产工作负载优先级的讨论不在本帖范围之内,而且取决于应用程序和工作负载组合。 如果我以后发现任何特定于 Caché 的建议,我可能会重新讨论这个话题。 有许多因素会影响到 CPU 调度器,本节只是简单提一下。 要深入了解,请参见帖子末尾的参考资料中的 VMware 白皮书及其他链接。 # 示例 为了说明不同的 vCPU 配置,我使用一个基于浏览器的高事务速率医院信息系统应用程序运行了一系列基准测试。 与 VMware 开发的 DVD 商店数据库基准测试的概念类似。 基准测试的脚本是根据现场医院实施的观测值和指标创建的,包括高使用率的工作流程、事务和使用最多系统资源的组件。 其他主机上的驱动虚拟机以设置的工作流程事务速率执行具有随机输入数据的脚本,来模拟 Web 会话(用户)。 1 倍速率的基准为基线。 速率可以按比例递增和递减。 除了数据库和操作系统指标外,一个很好的用来衡量基准数据库虚拟机性能的指标是在服务器上测量的组件(也可以是事务)响应时间。 一个组件示例是一部分最终用户屏幕。 组件响应时间增加意味着用户将开始看到应用程序响应时间变差。 性能良好的数据库系统必须为最终用户提供_一致的_高性能。 在下面的图表中,我针对一致的测试性能进行测量,并通过对 10 个最慢的高使用率组件的响应时间取平均值来表示最终用户体验。 预计平均组件响应时间为亚秒级,用户屏幕可能由一个组件组成,或者复杂的屏幕可能有多个组件。 > 请记住,您始终针对峰值工作负载进行规模调整,并且为意外的活动峰值留出缓冲区。 我通常以平均 80% 的峰值 CPU 利用率为目标。 基准测试硬件和软件的完整列表在帖子末尾。 ## 示例 1. 合理调整规模 - 每个主机一个怪兽虚拟机 可以创建一个可以使用主机服务器所有物理核心的数据库虚拟机,例如 24 物理核心主机上的 24 vCPU 虚拟机。 数据库虚拟机不会在 Caché 数据库镜像中“裸机”运行服务器以实现 HA,也不会引入操作系统故障转移集群的复杂性,而是包含在 vSphere 集群中实现管理和 HA,例如 DRS 和 VMware HA。 我见过有客户遵循老派的思维,根据五年硬件寿命结束时的预期容量来确定主数据库虚拟机的规模,但从上文可知,最好合理调整规模;如果虚拟机没有过度调整,性能和整合度会更好,并且管理 HA 将更容易;如果需要维护或主机出现故障,并且数据库怪兽虚拟机必须迁移或在其他主机上重启,想想俄罗斯方块的玩法就知道了。 如果预计事务速率显著增加,可以在计划维护期间提前增加 vCPU。 > 注意,“热添加”CPU 选项会禁用 vNUMA,因此不要将其用于怪兽虚拟机。 考虑下图显示的在 24 核主机上进行的一系列测试。 对于这个 24 核系统,3 倍事务速率是甜蜜点和容量规划目标。 - 主机上运行一个虚拟机。 - 使用了四种虚拟机规模来展示 12、24、36 和 48 vCPU 的性能。 - 尽可能对每种虚拟机规模都运行一系列事务速率(1 倍、2倍、3 倍、4 倍、5 倍)。 - 性能/用户体验以组件响应时间(条形图)的形式显示。 - 客户机虚拟机的 CPU 利用率百分比为平均值(线条)。 - 所有虚拟机规模中,主机 CPU 利用率都在 4 倍速率时达到 100%(红色虚线)。 ![24 物理核心主机 单个客户机虚拟机平均 CPU 百分比和组件响应时间 ](https://community.intersystems.com/sites/default/files/inline/images/single_guest_vm.png "单个客户机虚拟机") 这个图表中有许多信息,但我们可以关注几个有趣的事情。 - 24 vCPU 虚拟机(橙色)平稳地增加到目标 3 倍事务速率。 在 3 倍速率时,客户机内虚拟机的平均 CPU 利用率为 76%(峰值为 91% 左右)。 主机 CPU 利用率并不比客户机虚拟机高多少。 在 3 倍速率之前,组件响应时间非常稳定,因此用户很满意。 就我们的目标事务速率而言 — _这个虚拟机已合理调整规模_。 关于合理规模调整先说这么多,那么增加 vCPU 也就是使用超线程又会如何。 性能和可伸缩性有可能翻倍吗? 简短回答是_不可能!_ 在这种情况下,可以通过查看 4 倍以上速率的组件响应时间来了解答案。 虽然在分配了更多逻辑核心 (vCPU) 后性能“更好”,但仍然不平稳,不像 3 倍速率之前那样一致。 4 倍速率时,用户将报告响应时间变慢,无论分配多少个 vCPU。 请记住,在 4 倍速率时,_主机_曲线已经持平于 100% CPU 利用率,如 vSphere 所报告。 在 vCPU 数量较多的情况下,即使客户机内 CPU 指标 (vmstat) 报告低于 100% 利用率,对于物理资源来说情况也并非如此。 请记住,客户机操作系统不知道它是虚拟化的,它只是报告它所看到的资源。 另外,客户机操作系统也看不到超线程,所有 vCPU 都表现为物理核心。 关键是,数据库进程(在 3 倍事务速率时有 200 多个 Caché 进程)非常繁忙,并且非常高效地使用处理器,逻辑处理器没有很多空闲资源来调度更多工作,或将更多虚拟机整合到该主机。 例如,很大一部分 Caché 处理是在内存中进行的,因此没有很多 IO 等待。 所以,虽然可以分配比物理核心更多的 vCPU,但由于主机已经被 100% 利用,并不会获益许多。 Caché 非常擅长处理高工作负载。 即使主机和虚拟机的 CPU 利用率达到 100%,应用程序仍在运行,并且事务速率仍在提高 — 扩展不是线性的,如我们所见,响应时间越来越长,用户体验将受到影响 — 但应用程序不会“一落千丈”,尽管情况不是很好,但用户仍可以工作。 如果您的应用程序对响应时间不是那么敏感,那么很高兴地告诉您,您可以将其推向边缘甚至更远,并且 Caché 仍然可以安全地工作。 > 请记住,您不会想要以 100% CPU 运行数据库虚拟机或主机。 您需要容量来应对虚拟机的意外峰值和增长,而 ESXi 虚拟机监控程序需要资源来进行所有网络、存储和其他活动。 我总是针对 80% CPU 利用率的峰值进行规划。 即便如此,vCPU 的规模最多也只调整到物理核心数,这样即使在极端情况下,仍然有余量让 ESXi 虚拟机监控程序处理逻辑线程。 > 如果您运行超融合 (HCI) 解决方案,还必须考虑主机级别的 HCI CPU 要求。 有关详细信息,请参见我[先前关于 HCI](https://community.intersystems.com/post/intersystems-data-platforms-and-performance-%E2%80%93-part-8-hyper-converged-infrastructure-capacity "previous post on HCI") 的帖子。 部署在 HCI 上的虚拟机的基本 CPU 规模调整与其他虚拟机相同。 请记住,您必须在您自己的环境中使用您的应用程序验证和测试所有内容。 ## 示例 2. 资源过载 我看到过客户站点报告应用程序性能“慢”,而客户机操作系统却报告有空闲的 CPU 资源。 记住,客户机操作系统并不知道它是虚拟化的。 不幸的是,客户机内指标(例如 vmstat 在 pButtons 中报告的指标)可能具有欺骗性,您还必须获得主机级指标和 ESXi 指标(例如 `esxtop`)才能真正了解系统运行状况和容量。 如上面的图表所示,当主机报告 100% 利用率时,客户机虚拟机可能报告较低的利用率。 36 vCPU 虚拟机(红色)在 4 倍速率时报告 80% 平均 CPU 利用率,而主机报告 100%。 即使规模调整合理的虚拟机也可能出现资源短缺的情况,例如,如果在启动后有其他虚拟机迁移到主机上,或者由于 DRS 规则配置不当而导致资源过载。 为了显示关键指标,在下面的一系列测试中,我进行了以下配置: - 主机上运行两个数据库虚拟机。 - - 一个 24 vCPU 虚拟机以恒定的 2 倍事务速率运行(图表上未显示)。 - - 一个 24 vCPU 虚拟机以 1 倍、2 倍、3 倍事务速率运行(图表上显示这些指标)。 在另一个数据库使用资源的情况下;在 3 倍速率时,客户机操作系统 (RHEL 7) vmstat 只报告 86% 平均 CPU 利用率,运行队列大小平均只有 25。 然而,该系统的用户将大声抱怨,因为组件响应时间随着进程变慢而迅速增加。 如下图所示,协同停止和就绪时间说明了为什么用户性能如此糟糕。 就绪时间 (`%RDY`) 和协同停止 (`%CoStop`) 指标显示 CPU 资源在目标 3 倍速率下大幅过载。 这实际并不奇怪,因为_主机_以 2 倍速率运行(其他虚拟机),_而_该数据库虚拟机以 3 倍速率运行。 ![](https://community.intersystems.com/sites/default/files/inline/images/overcommit_3.png "过载的主机") 该图表明,当主机上的 总 CPU 负载增加时,就绪时间也会增加。 > 就绪时间是指虚拟机已准备好运行,但由于 CPU 资源不可用而无法运行的时间。 协同停止也会增加。 没有足够的空闲逻辑 CPU 来允许数据库虚拟机运行(正如我在上面的超线程部分详细说明的那样)。 最终结果是由于对物理 CPU 资源的争用而导致处理延迟。 我曾在一个客户站点看到过这种情况,当时通过 pButtons 和 vmstat 获取的支持视图只显示了虚拟化的操作系统。 虽然 vmstat 报告还有 CPU 余量,但用户的性能体验非常糟糕。 这里的教训是,直到 ESXi 指标和主机级视图可用,才能诊断出真正的问题;一般的集群 CPU 资源短缺导致的 CPU 资源过载,以及使情况变得更糟的不良 DRS 规则,会使高事务数据库虚拟机一起迁移并使主机资源不堪重负。 ## 示例 3. 资源过载 在此示例中,我使用了一个以 3 倍事务速率运行的基准 24 vCPU 数据库虚拟机,然后使用两个以恒定 3 倍事务速率运行的 24 vCPU 数据库虚拟机。 虚拟机的平均基准 CPU 利用率(见上面的示例 1)为 76%,主机则为 85%。 单个 24 vCPU 数据库虚拟机会使用全部 24 个物理处理器。 运行两个 24 vCPU 虚拟机意味着这两个虚拟机将争用资源,并使用服务器上的全部 48 个逻辑执行线程。 ![](https://community.intersystems.com/sites/default/files/inline/images/overcommit_2vm.png "过载的主机") 请记住,在运行单个虚拟机时,主机并没有被 100% 利用,我们仍然可以看到,当两个非常繁忙的 24 vCPU 虚拟机试图使用主机上的 24 个物理核心(即使开启了超线程)时,吞吐量和性能显著下降。 尽管 Caché 非常有效地使用了可用的 CPU 资源,但每个虚拟机的数据库吞吐量仍然下降了 16%,更重要的是,组件(用户)响应时间增加了 50% 以上。 ## 总结 本帖的目的是回答几个常见问题。 要深入了解 CPU 主机资源和 VMware CPU 调度器,请参见下面的参考部分。 虽然有许多专业级的调整,并且要深入研究 ESXi 才能榨干系统的最后一点性能,但基本规则非常简单。 对于_大型生产数据库_: - 为每个物理 CPU 核心规划一个 vCPU。 - 考虑 NUMA 并按理想情况调整虚拟机规模,以使 CPU 和内存对于 NUMA 节点是本地的。 - 合理调整虚拟机规模。 仅在需要时才添加 vCPU。 如果您想要整合虚拟机,请记住,大型数据库非常繁忙,在高峰期会大量使用 CPU(物理和逻辑)。 在您的监视系统告诉您安全之前,不要超额预定 CPU。 ## 参考 - [VMware 博客 - 怪兽虚拟机何时过载 vCPU:pCPU](https://blogs.vmware.com/vsphere/2014/02/overcommit-vcpupcpu-monster-vms.html) - [2016 NUMA 深入研究系列介绍](http://frankdenneman.nl/2016/07/06/introduction-2016-numa-deep-dive-series) - [VMware vSphere 5.1 中的 CPU 调度器](http://www.vmware.com/content/dam/digitalmarketing/vmware/en/pdf/techpaper/vmware-vsphere-cpu-sched-performance-white-paper.pdf) ## 测试 我在一个 vSphere 集群上运行了本帖中的示例,该集群包括连接到一个全闪存阵列的双处理器 Dell R730。 在示例运行期间,网络或存储没有出现瓶颈。 - Caché 2016.2.1.803.0 PowerEdge R730 - 2 个 Intel(R) Xeon(R) CPU E5-2680 v3 @ 2.50GHz - 16 条 16GB RDIMM,2133 MT/s,双列,x4 数据宽度 - SAS 12Gbps HBA 外部控制器 - 超线程 (HT) 开启 PowerVault MD3420,12G SAS,2U-24 驱动器 - 24 个 960GB 固态硬盘 SAS 读取密集型 MLC 12Gbps 2.5 英寸热拔插驱动器,PX04SR - 2 个控制器,12G SAS,2U MD34xx,8G 缓存 VMware ESXi 6.0.0 build-2494585 - 按照最佳实践配置虚拟机;VMXNET3、PVSCSI 等 RHEL 7 - 大页面 基准 1 倍速率下平均每秒 700,000 gloref(每秒数据库访问次数)。 24 vCPU 在 5 倍速率下平均每秒超过 3,000,000 gloref。 测试以老化方式进行,直到达到稳定的性能,然后进行 15 分钟采样并取平均值。 > 这些示例只是为了说明理论,您必须使用自己的应用程序进行验证!
文章
Hao Ma · 一月 15, 2021

IAM实践指南——OAuth 2.0下的API保卫战(第二部分)

在这个由三部分组成的系列文章中,我们将展示如何在OAuth 2.0标准下使用IAM简单地为IRIS中的未经验证的服务添加安全性。 在第一部分中,我们介绍了一些OAuth 2.0背景知识,以及IRIS和IAM的初始定义和配置,以帮助读者理解确保服务安全的整个过程。 现在,本文将详细讨论和演示配置IAM所需的步骤——验证传入请求中的访问令牌,并在验证成功时将请求转发到后端。 本系列的最后一部分将讨论和演示IAM生成访问令牌(充当授权服务器)并对其进行验证时所需的配置,以及一些重要的最终考虑事项。 如果您想试用IAM,请联系InterSystems销售代表。 场景1:IAM作为访问令牌验证器 在该场景中,需要使用一个外部授权服务器生成JWT(JSON Web Token)格式的访问令牌。该JWT使用了RS256算法和私钥签名。为了验证JWT签名,另一方(本例中是IAM)需要拥有授权服务器提供的公钥。 由外部授权服务器生成的JWT主体中还包括一个名为“exp”的声明(包含该令牌过期的时间戳),以及另一个名为“iss”的声明(包含授权服务器的地址)。 因此,IAM需要先使用授权服务器的公钥和JWT内部“exp”声明中包含的过期时间戳对JWT签名进行验证,然后再将请求转发给IRIS。 对IAM进行相应配置时,首先要向IAM中的“SampleIRISService”添加一个名为“JWT”的插件。为此,请转到IAM中的Services页面并复制“SampleIRISService”的ID,稍后会用到。 之后,打开插件,点击“New Plugin”按钮,找到“JWT”插件,点击启用。 在下个页面中,将“SampleIRISService”ID粘贴在“service_id”字段中,然后在“config.claims_to_verify”参数中选中“exp”框。 注意,“config.key_claim_name”参数的值是“iss”。后面会用到。 然后,点击“Create”按钮。 完成操作后,找到左侧菜单中的“Consumers”部分,然后单击先前创建的“ClientApp”。点击“Credentials”标签,然后单击按钮“New JWT Credential”。 在下一页中,选择JWT签名算法(本例中为RS256),并将公钥(这是授权服务器提供的PEM格式的公钥)粘贴到“rsa_public_key”字段中。 在“key”字段中,在添加JWT插件时需要用到之前在“config.key_claim_name”字段中输入的JWT声明内容。所以在本例中,需要插入的是JWT的iss声明内容(本例中是授权服务器的地址)。 之后,单击“Create”按钮。 提示:出于调试目的,可以使用一个在线工具对JWT进行解码,将公钥粘贴进去就可以检查声明内容及其值,并且验证签名。该在线工具的链接如下:https://jwt.io/#debugger 现在,添加了JWT插件后,就不能发送未经身份验证的请求了。如下所示,对URL的一个简单GET请求(未经身份验证): http://iamhost:8000/event/1 返回一个未经授权的信息,以及状态码“401未经授权”。 为了从IRIS获得结果,需要将JWT添加到请求中。 首先,需要向授权服务器请求JWT。如果POST请求与主体中的一些键值对(包括用户和客户端信息)一起发出,那么在这里使用的自定义授权服务器将向以下URL返回一个JWT: https://authorizationserver:5001/auth 该请求及其响应如下所示: 然后,可以将响应中获得的JWT添加到授权标头中作为Bearer令牌使用,并将GET请求发送到和之前相同的URL: http://iamhost:8000/event/1 或者将它作为querystring参数添加进去。当添加JWT插件(本例中是“jwt”)时,querystring关键字是在“config.uri_param_names”字段中指定的值 最后,如果在“config.cookie_names”字段中输入任意名称,选择将JWT作为cookie包含在请求中。 请继续阅读本系列的第三部分也即最后一部分,了解IAM生成和验证访问令牌所需的配置,以及一些重要的最终考虑因素。
文章
姚 鑫 · 五月 31, 2021

第十二章 IBM WebSphere MQ检索邮件

# 第十二章 IBM WebSphere MQ检索邮件 # 检索邮件 要检索邮件,请执行以下操作: 1. 按照“创建连接对象”中的说明创建连接对象。在这种情况下,请创建`%Net.MQRecv`的实例。`Connection`对象有一个消息队列,可以从中检索消息。 2. 根据需要调用以下方法: - `%Get()`-通过引用返回字符串消息作为第一个参数。 - `%GetStream()`-给定初始化的文件字符流,此方法从队列中检索消息,并将其放入与该流关联的文件中。请注意,必须设置流的`Filename`属性才能对其进行初始化。不支持二进制流。 3. 检查调用的方法返回的值。请参阅“获取错误代码”。请记住,当队列为空时,IBM `WebSphere MQ`返回`2033`。 4. 检索完消息后,调用`Connection`对象的`%Close()`方法以释放动态链接库的句柄。 示例1:`ReceiveString()` 下面的类方法从`mqtest`队列检索消息。 ```java ///Method returns string or null or error message ClassMethod ReceiveString() As %String { Set recv=##class(%Net.MQRecv).%New() Set queue="mqtest" Set qm="QM_antigua" Set chan="S_antigua/TCP/antigua(1414)" Set logfile="c:\mq-recv-log.txt" Set check=recv.%Init(queue,qm,chan,logfile) If 'check Quit recv.%GetLastError() Set check=recv.%Get(.msg) If 'check { Set reasoncode=recv.%GetLastError() If reasoncode=2033 Quit "" Quit "ERROR: "_reasoncode } Quit msg } ``` 示例2:`ReceiveCharacterStream()` 以下方法可以检索更长的消息,因为它使用`%GetStream()`: ```java /// Method returns reason code from IBM WebSphere MQ ClassMethod ReceiveCharacterStream() As %Integer { Set recv=##class(%Net.MQRecv).%New() Set queue="mqtest" Set qm="QM_antigua" Set chan="S_antigua/TCP/antigua(1414)" Set logfile="c:\mq-recv-log.txt" Set check=recv.%Init(queue,qm,chan,logfile) If 'check Quit recv.%GetLastError() //initialize the stream and tell it what file to use //make sure filename is unique we can tell what we received Set longmsg=##class(%FileCharacterStream).%New() Set longmsg.Filename="c:\mq-received"_$h_".txt" Set check=recv.%GetStream(longmsg) If 'check Quit recv.%GetLastError() Quit check } ``` # 更新消息信息 `%Net.MQSend`和`%Net.MQRecv`类还提供以下方法: ### %CorId() (通过引用)更新上次读取的邮件的关联ID。 ### %ReplyQMgrName() (通过引用)更新上次读取的消息的回复队列管理器名称。 ### %ReplyQName() (通过引用)更新上次读取的消息的回复队列名称。 # Troubleshooting 如果在使用IBM `WebSphere MQ`的InterSystems IRIS接口时遇到问题,应该首先确定客户端是否安装正确并且可以与服务器通信。要执行这样的测试,可以使用IBM `WebSphere MQ`提供的示例程序。可执行文件位于IBM `WebSphere MQ`客户端的bin目录中。 以下步骤介绍如何在`Windows`上使用这些示例程序。在其他操作系统上,细节可能会有所不同;请参考IBM文档并检查您的客户端中存在的文件的名称。 1. 创建一个名为`MQSERVER`的环境变量。它的值的格式应该是`channel_name/Transport/server`,其中`channel_name`是要使用的通道的名称,`Transport`是指示要使用的传输的字符串,而`server`是服务器的名称。例如:`S_Antigua/TCP/Antigua` 2. 在命令行中,输入以下命令: ```java amqsputc queue_name queue_manager_name ``` 其中,`QUEUE_NAME`是要使用的队列的名称,`QUEUE_MANAGER_NAME`是队列管理器的名称。例如: ```java amqsputc mqtest QM_antigua ``` 如果`amqsputc`命令无法识别,请确保已更新`PATH`环境变量以包括IBM `WebSphere MQ`客户端的bin目录。 3. 应该会看到几行代码,如下所示: ```java Sample AMQSPUT0 start target queue is mqtest ``` 4. 现在可以发送消息了。只需键入每条消息,然后在每条消息后按Enter键即可。例如: ```java sample message 1 sample message 2 ``` 5. 发送完邮件后,按两次Enter键。然后,将看到如下所示的行: ```java Sample AMQSPUT0 end ``` 6. 要完成此测试,我们将检索发送到队列的消息。在命令行中键入以下命令: ```java amqsgetc queue_name queue_manager_name ``` 其中,`QUEUE_NAME`是要使用的队列的名称,`QUEUE_MANAGER_NAME`是队列管理器的名称。例如: 7. 然后,应该看到一个起始行,后跟之前发送的消息,如下所示: ```java Sample AMQSGET0 start message message ``` 8. 此示例程序短暂等待接收任何其他消息,然后显示以下内容: ```java no more messages Sample AMQSGET0 end ``` 如果测试失败,请参考IBM文档。问题的可能原因包括以下几个方面: - 安全问题 - 队列定义不正确 - 队列管理器未启动
文章
Hao Ma · 十一月 17, 2021

开发Ensemble REST服务

REF: https://docs.intersystems.com/healthconnectlatest/csp/docbook/Doc.View.cls?KEY=GREST REF: https://docs.intersystems.com/healthconnectlatest/csp/docbook/DocBook.UI.Page.cls?KEY=AFL_rest#AFL_C4838 开发REST服务有两个方式, 一个是生生的写代码, 定义接口的标准,被称为"Manually Coding"。第2个方式是目前越来越流行的"Sepcification-first",也就是使用描述性的语言定义接口规范,然后通过这个规范生成接口代码。第2种方式更快捷,但这里我还是从第一种介绍起,对理解里面的代码层次更容易一些,而这是调试一个接口必须的。 从代码开发REST服务 不同于HTTP和SOAP, Ensemble里面没有REST的inbound Adaptor,也没有可用的BS组件。在Production里开发一个REST服务的步骤是: 1. 开发一个REST Service, 这个Service是一个CSP Page, 是一个网页服务,和Ensemble没关系。要在Production中使用这个服务,您需要在这个服务里调用一个Production的业务服务BS。 2. 要访问这个REST页面服务, 您需要配置一个Web Application。Web Application的配置项上有一个选项: "REST 分派类"。这样配置好之后, Web Application收到相应的URL后就会调用这个REST页面,页面再去调用Production的BS。 3. 最后,您需要在BS中处理收到的JSON, 发送给其他组件,以传递给接收方系统。 如果您看的了代码包里的EnsLib.REST.Service类, 它继承了%CSP.REST页面, 也继承了BusinessService,非常符合Ensemble的结构设计。But, 别用。在线文档中有专门的说明。 Although InterSystems IRIS defines a class EnsLib.REST.ServiceOpens in a new window, that is a subclass of %CSP.RESTOpens in a new window, we recommend that you not use this class because it provides an incomplete implementation of %CSP.REST Opens in a new window. 让我们开始开发一个简单的REST服务并加入Production: Step 1: 创建以下代码,解释一下: - 继承%CSP.REST,这是个专用于REST的CSP页面 - UrlMap是一个XData, 在COS语言里用于在代码里放置固定的xml数据结构。UrlMap定义从收到的URL到本类里不同的方法之间的映射。 - 方法中入参可以是任意的数据结构和用户定义的类结构,不需要出参。如果直接返回消息给调用者,直接"write"一个流或者字符串 Class SEDemo.IO.REST.SampleService Extends %CSP.REST { XData UrlMap [ XMLNamespace = "http://www.intersystems.com/urlmap" ] { } ClassMethod Test(pInput As %String) As %Status { write "Received: "_pInput,! Quit 1 } ClassMethod GetPatientById(pID As %String) As %Status { Try{ Set tObj=##class(SEDemo.Common.Patient).%OpenId(pID),tStream = "" d ##class(%ZEN.Auxiliary.jsonProvider).%WriteJSONStreamFromObject(.tStream,tObj) w tStream.Read() } Catch (e) {Set tSC=e.AsStatus()} Quit tSC } } Step 2: 创建Web Application 在管理界面System Administration > Security > Applications > Web Applications,创建一个用于接收此REST服务的Web APPlication, 设置"Dispatch Class"为当前类。 假设创建的Web Applicaiton为"/CSP/myrest",注意: - 选中“Enable Application" - 权限: 分配本命名空间数据库的资源,默认是%DB_%Default。 后面会详细介绍权限和用户管理的细节。 Step 3: 测试你的REST service 你可以选择自己喜欢的测试方式,比如用浏览器,POSTMAN, SoapUI..., 下面是我测试的记录: CNMBPHMA:~ hma$ curl -v http://172.16.58.200:52773/csp/myrest/Test/333 * Trying 172.16.58.200... * TCP_NODELAY set * Connected to 172.16.58.200 (172.16.58.200) port 52773 (#0) > GET /csp/myrest/Test/333 HTTP/1.1 > Host: 172.16.58.200:52773 > User-Agent: curl/7.54.0 > Accept: */* > < HTTP/1.1 200 OK < Date: Wed, 14 Jul 2021 06:47:26 GMT < Server: Apache < CACHE-CONTROL: no-cache < EXPIRES: Thu, 29 Oct 1998 17:04:19 GMT < PRAGMA: no-cache < CONTENT-LENGTH: 15 < Content-Type: text/html; charset=utf-8 < Received: 333 * Connection #0 to host 172.16.58.200 left intact CNMBPHMA:~ hma$ 这里是一个匿名访问,如果需要用户认证,修改一下重发: CNMBPHMA:~ hma$ curl -u 'superuser:SYS' http://172.16.58.200:52773/csp/myrest/Test/333 Received: 333 CNMBPHMA:~ hma$ 注意两点: 1. 到目前为止我们测试的其实是一个HTTP请求和响应,虽然内部用了%CSP.REST的类, 但响应中'Content-Type'还是'text/html' 2. 代码中没有处理出错和查不到结果的情况 3. 到目前为止和Ensemble Production没有任何关系。 Step 4: 将服务加入Ensemble Production 加入Production的意思实际上时调用一个Production的BusinessService。 让我们先创建一个简单的Service. ///不使用Adapter, 收到任何请求,同步发送给目标组件 Class Test.BS.GeneralService Extends Ens.BusinessService { Method OnProcessInput(pInput As %RegisteredObject, Output pOutput As %RegisteredObject) As %Status { set tRequest=##class(Ens.StringRequest).%New() Set tStatus = ..SendRequestSync("Test.BO.dummyOperation", tRequest, .tResponse) set pOutput = tResponse Quit tStatus } } 当需要前面的REST服务来调用这个BusinessService的时候, 需要在method里面加入直接调用的语句,比如上面的GetPatientById() ClassMethod GetPatientById(pID As %String) As %Status { set status = ##class(Ens.Director).CreateBusinessService("Test.BS.GeneralService", .tService) if $$$ISOK(status) { set status = service.OnProcessInput(pID, .tResponse) } w tResponse,! }
文章
姚 鑫 · 六月 10, 2021

第三章 指定输出的字符集

# 第三章 指定输出的字符集 # 指定输出的字符集 若要指定要在输出文档中使用的字符集,可以设置Writer实例的Charset属性。选项包括`“UTF-8”`、`“UTF-16”`以及InterSystems IRIS支持的其他字符集。 # Writing the Prolog XML文件的序言(根元素之前的部分)可以包含文档类型声明、处理指令和注释。 ## 影响Prolog的属性 在`writer`实例中,以下属性会影响`prolog`: ### Charset 控制两件事`:XML`声明中的字符集声明和(相应的)输出中使用的字符集编码。 ### NoXmlDeclaration 控制输出是否包含XML声明。在大多数情况下,默认值是0,这意味着已经编写了声明。如果没有指定字符集,并且输出定向到字符串或字符流,则默认为1,并且不写入任何声明。 ## 生成文档类型声明 在根元素之前,可以包含文档类型声明,该声明声明了文档中使用的模式。 要生成文档类型声明,需要使用`WriteDocType()`方法,该方法有一个必选参数和三个可选参数。 就本文档而言,文档类型声明包括以下可能的部分: ```java ``` 如这里所示,文档类型有一个名称,根据XML规则,该名称必须是根元素的名称。 声明可以包含外部子集、内部子集或两者。 external_subset 部分指向其他地方的DTD文件。 本节的结构是以下任何一种: ```java PUBLIC public_literal_identifier PUBLIC public_literal_identifier system_literal_identifier SYSTEM system_literal_identifier ``` 这里`public_literal_identifier`和`system_literal_identifier`是包含DTD uri的字符串。 注意,DTD可以同时具有公共标识符和系统标识符。 下面是一个文档类型声明示例,它包含一个同时使用公共标识符和系统标识符的外部子集: ```java ``` internal_subset部分是一组实体声明。 下面是一个文档类型声明的示例,它只包含一组内部声明: ```java !ENTITY city (#PCDATA)> !ENTITY player (#PCDATA)> ] > ``` `WriteDocType()`方法有四个参数: - 第一个参数指定文档类型的名称,用于在这个XML文档中使用。 这是必需的,而且必须是有效的XML标识符。 还必须将此名称用作本文档中根级别元素的名称。 - 可选的第二个和第三个参数指定声明的外部部分,如下所示: WriteDocType参数 第二个参数 | 第三个参数| 其他部分 ---|---|--- “publicURI” |null| PUBLIC “publicURI” “publicURI” |“systemURI”| PUBLIC “publicURI” “systemURI” null |“systemURI”| SYSTEM “systemURI” - 可选的第四个参数指定声明的内部部分。如果此参数非空,则将其括在方括号`[]`中,并适当地放在声明的末尾。没有添加其他字符。 ## 编写处理指令 要将处理指令写入`XML`,请使用`WriteProcessingInstruction()`方法,该方法有两个参数: 1. 处理指令(也称为目标)的名称。 2. 指令本身是一个字符串。 该方法将以下内容写入XML: ```java ``` 例如,要编写以下处理指令: ```java ``` 为此,可以按如下方式调用`WriteProcessingInstruction()`方法: ```java set instructions="type=""text/css"" href=""mystyles.css""" set status=writer.WriteProcessingInstruction("xml-stylesheet", instructions) ``` ## 指定默认命名空间 在编写器实例中,可以指定默认命名空间,该命名空间仅应用于没有`Namespace`参数设置的类。有几个选项: - 可以在输出方法中指定默认命名空间。四个主要的输出方法(`RootObject()`、`RootElement()`、`Object()`或`Element()`)都接受名称空间作为参数。只有在类定义中未设置`Namespace`参数时,才会将相关元素分配给`Namespace`。 - 可以为编写器实例指定总体默认命名空间。为此,请为编写器实例的`DefaultNamespace`属性指定值。 ```java Class Writers.BasicDemoPerson Extends (%RegisteredObject, %XML.Adaptor) { Parameter XMLNAME = "Person"; Property Name As %Name; Property DOB As %Date; } ``` 默认情况下,如果我们只是导出此类的对象,我们会看到如下所示的输出: ```java Persephone MacMillan 1976-02-20 ``` 相反,如果我们在编写器实例中`将DefaultNamespace`设置为`"http://www.person.org",`然后导出一个对象,则会收到如下所示的输出: ```java Persephone MacMillan 1976-02-20 ``` 在本例中, `` 元素使用默认名称空间,否则不会分配给名称空间。
文章
Frank Ma · 六月 13, 2022

使用IRIS IntegratedML(一体化机器学习)预测孕产妇风险的Web应用

孕产妇风险可以通过一些医学界众所周知的参数来测量。这样,为了帮助医学界和计算机系统,特别是人工智能,科学家Yasir Hussein Shakir发布了一个非常有用的数据集,用于训练检测/预测孕产妇风险的机器学习(ML)算法。这份出版物可以在最大和最知名的ML数据库Kaggle上找到,网址是 https://www.kaggle.com/code/yasserhessein/classification-maternal-health-5-algorithms-ml. 关于数据集 由于缺乏怀孕期间和怀孕后的孕产妇保健信息,许多孕妇死于怀孕问题。这在农村地区和新兴国家的中下层家庭中更为常见。在怀孕期间,应时刻注意观察,以确保婴儿的正常成长和安全分娩 (来源: https://www.kaggle.com/code/yasserhessein/classification-maternal-health-5-algorithms-ml). 数据是通过基于物联网的风险监测系统,从不同的医院、社区诊所、孕产妇保健机构收集而来。 Age(年龄): 妇女怀孕时的年龄,以岁为单位。 SystolicBP (收缩压): 血压的最高值(mmHg),这是怀孕期间的另一个重要属性。 DiastolicBP(舒张压): 血压的较低值(mmHg),这是怀孕期间的另一个重要属性。 BS(血糖): 血糖水平是以摩尔浓度为单位,即mmol/L。 HeartRate(心率): 正常的静息心率,单位是每分钟的心跳次数。 Risk Level(风险等级): 基于前边的属性所预测的孕期风险强度水平。 从Kaggle获取孕产妇的风险数据 来自Kaggle的孕产妇风险数据可以通过Health-Dataset(健康数据集)应用程序加载到IRIS表中: https://openexchange.intersystems.com/package/Health-Dataset. 要做到这一点,在你的module.xml项目中,设置依赖关系(Health Dataset的ModuleReference): Module.xml with Health Dataset application reference <?xml version="1.0" encoding="UTF-8"?> <Export generator="Cache" version="25"> <Document name="predict-diseases.ZPM"> <Module> <Name>predict-diseases</Name> <Version>1.0.0</Version> <Packaging>module</Packaging> <SourcesRoot>src/iris</SourcesRoot> <Resource Name="dc.predict.disease.PKG"/> <Dependencies> <ModuleReference> <Name>swagger-ui</Name> <Version>1.*.*</Version> </ModuleReference> <ModuleReference> <Name>dataset-health</Name> <Version>*</Version> </ModuleReference> </Dependencies> <CSPApplication Url="/predict-diseases" DispatchClass="dc.predict.disease.PredictDiseaseRESTApp" MatchRoles=":{$dbrole}" PasswordAuthEnabled="1" UnauthenticatedEnabled="1" Recurse="1" UseCookies="2" CookiePath="/predict-diseases" /> <CSPApplication CookiePath="/disease-predictor/" DefaultTimeout="900" SourcePath="/src/csp" DeployPath="${cspdir}/csp/${namespace}/" MatchRoles=":{$dbrole}" PasswordAuthEnabled="0" Recurse="1" ServeFiles="1" ServeFilesTimeout="3600" UnauthenticatedEnabled="1" Url="/disease-predictor" UseSessionCookie="2" /> </Module> </Document> </Export> Web Frontend and Backend Application to Predict Maternal Risk Go to Open Exchange app link (https://openexchange.intersystems.com/package/Disease-Predictor) and follow these steps: 使用Clone/git 把repo拉到任一本地目录中: $ git clone https://github.com/yurimarx/predict-diseases.git 在该文件夹中打开Docker 终端并运行: $ docker-compose build 运行IRIS容器: $ docker-compose up -d 进入管理门户执行查询,训练AI模型: http://localhost:52773/csp/sys/exp/%25CSP.UI.Portal.SQL.Home.zen?$NAMESPACE=USER 创建用于训练的VIEW(视图): CREATE VIEW MaternalRiskTrain AS SELECT BS, BodyTemp, DiastolicBP, HeartRate, RiskLevel, SystolicBP, age FROM dc_data_health.MaternalHealthRisk 使用视图创建AI模型: CREATE MODEL MaternalRiskModel PREDICTING (RiskLevel) FROM MaternalRiskTrain 训练模型: TRAIN MODEL MaternalRiskModel 访问 http://localhost:52773/disease-predictor/index.html ,使用 Disease Predictor(疾病预测器)前端进行疾病预测,如下: 幕后工作 预测孕产妇风险疾病的后端类方法 InterSystems IRIS允许你执行SELECT,使用之前创建的模型进行预测。 Backend ClassMethod to predict Maternal Risk /// Predict Maternal Risk ClassMethod PredictMaternalRisk() As %Status { Try { Set data = {}.%FromJSON(%request.Content) Set %response.Status = 200 Set %response.Headers("Access-Control-Allow-Origin")="*" Set qry = "SELECT PREDICT(MaternalRiskModel) As PredictedMaternalRisk, " _"age, BS, BodyTemp, DiastolicBP, HeartRate, SystolicBP " _"FROM (SELECT "_data.BS_" AS BS, " _data.BodyTemp_" As BodyTemp, " _data.DiastolicBP_" AS DiastolicBP, " _data.HeartRate_" AS HeartRate, " _data.SystolicBP_" As SystolicBP, " _data.Age_" AS age)" Set tStatement = ##class(%SQL.Statement).%New() Set qStatus = tStatement.%Prepare(qry) If qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT} Set rset = tStatement.%Execute() Do rset.%Next() Set Response = {} Set Response.PredictedMaternalRisk = rset.PredictedMaternalRisk Set Response.Age = rset.Age Set Response.SystolicBP = rset.SystolicBP Set Response.DiastolicBP = rset.DiastolicBP Set Response.BS = rset.BS Set Response.BodyTemp = rset.BodyTemp Set Response.HeartRate = rset.HeartRate Write Response.%ToJSON() Return 1 } Catch err { write !, "Error name: ", ?20, err.Name, !, "Error code: ", ?20, err.Code, !, "Error location: ", ?20, err.Location, !, "Additional data: ", ?20, err.Data, ! Return 0 } } 现在,任何web应用都可以进行预测并显示结果。请在预测疾病应用程序的前端文件夹中查看源代码。
文章
姚 鑫 · 六月 22, 2021

第十五章 XML检查属性

# 第十五章 XML检查属性 # 检查属性的基本方法 可以使用`%XML.Node`的以下方法。以检查当前节点的属性。 - `AttributeDefined()` 如果当前元素具有具有给定名称的属性,则返回非零(TRUE)。 - `FirstAttributeName()` 返回当前元素的第一个属性的属性名称。 - `GetAttributeValue()` 返回给定属性的值。如果元素没有该属性,则该方法返回NULL。 - `GetNumberAttributes()` 返回当前元素的属性数。 - `LastAttributeName()` 返回当前元素的最后一个属性的属性名称。 - `NextAttributeName()` 在给定属性名称的情况下,无论指定的属性是否有效,此方法都会按排序顺序返回下一个属性的名称。 - `PreviousAttributeName()` 在给定属性名称的情况下,无论指定的属性是否有效,此方法都会按排序顺序返回上一个属性的名称。 下面的示例遍历给定节点中的属性并编写一个简单报表: ```java /// d ##class(Demo.XmlDemo).ShowAttributes("David Marston") /// David Marston ClassMethod ShowAttributes(string) { set reader=##class(%XML.Reader).%New() set status=reader.OpenString(string) if $$$ISERR(status) {do $System.Status.DisplayError(status)} s node = reader.Document.GetDocumentElement() b s count = node.GetNumberAttributes() w !, "属性数量: ", count s first = node.FirstAttributeName() w !, "第一个属性是: ", first w !, " 值是: ",node.GetAttributeValue(first) s next = node.NextAttributeName(first) for i = 1 : 1 : count - 2 { w !, "下一个属性是: ", next w !, " 值是: ",node.GetAttributeValue(next) s next = node.NextAttributeName(next) } s last = node.LastAttributeName() w !, "最后一个属性是: ", last w !, " 值是: ",node.GetAttributeValue(last) } ``` 示例XML文档: ```xml David Marston ``` 如果将此文档的第一个节点传递给示例方法,则会看到以下输出: ```java Number of attributes: 5 First attribute is: attr1 Its value is: first Next attribute is: attr2 Its value is: second Next attribute is: attr3 Its value is: third Next attribute is: attr4 Its value is: fourth Last attribute is: attr5 Its value is: fifth ``` # 检查属性的其他方法 本节讨论可用于获取任何属性的名称、值、命名空间、`QName`和值命名空间的方法。这些方法分为以下几组: - 仅使用属性名称的方法 - 使用属性名称和命名空间的方法 注意:在XML标准中,一个元素可以包含多个同名的属性,每个属性位于不同的名称空间中。但是,在InterSystems IRIS XML中,这是不受支持的。 ## 仅使用属性名称的方法 使用以下方法获取有关属性的信息。 ### GetAttribute() ```java method GetAttribute(attributeName As %String, ByRef namespace As %String, ByRef value As %String, ByRef valueNamespace As %String) ``` 返回给定属性的数据。此方法通过引用返回下列值: - `Namespace`是来自属性QName的命名空间URI - `value` 是属性值。 - `valueNamespace` 值所属的命名空间URI。例如,以下属性: ``` xsi:type="s:string" ``` 此属性的值为字符串,并且此值位于使用前缀s在其他位置声明的命名空间中。假设本文档的较早部分包含以下命名空间声明: ```java xmlns:s="http://www.w3.org/2001/XMLSchema" ``` 在本例中,`valueNamespace`将为`“http://www.w3.org/2001/XMLSchema”`. ### GetAttributeNamespace() ```java method GetAttributeNamespace(attributeName As %String) as %String ``` 从当前元素的名为`AttributeName`的属性的`QName`返回命名空间URI。 ### GetAttributeQName() ```java method GetAttributeQName(attributeName As %String) as %String ``` 返回给定属性的`QName`。 ### GetAttributeValue() ```java method GetAttributeValue(attributeName As %String) as %String ``` 返回给定属性的值。 ### GetAttributeValueNamespace() ```java method GetAttributeValueNamespace(attributeName As %String) as %String ``` 返回给定属性的值的命名空间。 ## 使用属性名和命名空间的方法 要同时使用属性名称及其命名空间来获取有关属性的信息,请使用以下方法: ### GetAttributeNS() ```java method GetAttributeNS(attributeName As %String, namespace As %String, ByRef value As %String, ByRef valueNamespace As %String) ``` 返回给定属性的数据,其中`AttributeName`和`Namespace`指定感兴趣的属性。此方法通过引用返回以下数据: - `value` 是属性值。 - `valueNamespace` 值所属的命名空间URI。例如,以下属性: ```java xsi:type="s:string" ``` 此属性的值为字符串,并且此值位于使用前缀s在其他位置声明的命名空间中。假设本文档的较早部分包含以下命名空间声明: ```java xmlns:s="http://www.w3.org/2001/XMLSchema" ``` ### GetAttributeQNameNS() ```java method GetAttributeQNameNS(attributeName As %String, namespace As %String) as %String ``` 返回给定属性的`QName`,其中`AttributeName`和`Namespace`指定感兴趣的属性。 ### GetAttributeValueNS() ```java method GetAttributeValueNS(attributeName As %String, namespace As %String) as %String ``` 返回给定属性的值,其中`AttributeName`和`Namespace`指定感兴趣的属性。 ### GetAttributeValueNamespaceNS ```java method GetAttributeValueNamespaceNS(attributeName As %String, namespace As %String) as %String ``` 返回给定属性的值的命名空间,其中`AttributeName`和`Namespace`指定感兴趣的属性。
文章
Hao Ma · 五月 15

IRIS/Caché SQL优化经验分享 - 优化关键字

SQL查询优化器一般情况下能给出最好的查询计划,但不是所有情况都这样,所以InterSystems SQL还提供了一个方式, 也就是在查询语句里加入`optimize-option keyword(优化关键字)`, 用来人工的修改查询计划。 比如下面的查询: ```sql SELECT AVG(SaleAmt) FROM %PARALLEL User.AllSales GROUP BY Region ``` 其中的%PARALLEL, 就是最常用的优化关键字, 它强制SQL优化器使用多进程并行处理这个SQL。 您可以这样理解: 如果查询优化器足够聪明,那么绝大多数情况下,根本就不需要优化关键字来人工干预。因此,您也一定不奇怪在不同的IRIS/Caché版本中, 关键字的表现可能不一样。越新的版本,应该是越少用到。比如上面的%PARALLEL, 在Caché的大多数版本中, 在查询中加上它一般都能提高查询速度,而在IRIS中,尤其是2023版本以后, 同样的SQL查询语句,很大的可能查询优化器已经自动使用多进程并行查询了,不再需要用户人工干预了。 因此,先总结有关优化关键字的要点: 1. 优化关键字主要是FROM语句中使用。 UPDATE, INSERT语句也有可以使用的关键字,比如%NOJOURAL等等, 这里我不介绍了,请各位自己查询文档。 > INSERT, UPDATE的关键字常用的有:%NOCHECK %NOINDEX %NOLOCK %NOTRIGGER 等等 2. 各个不同版本的文档中这部分内容有少许的不同。 3. 使用查询关键字要结合阅读查询计划,需要经验的积累。用的多了, 在当前版本什么样的查询需要添加关键字就比较有数了。 最新版本的联机文档在: [Specify Optimization Hints in Queries | Configure SQL Performance Options](https://docs.intersystems.com/iris20241/csp/docbook/DocBook.UI.Page.cls?KEY=GSOC_hints#GSOC_hints_clausekeys) ## %PARALLEL 指定查询使用多个进程并行处理。在Query Plan中您可以得到证实。有关Query Plan的阅读请看前面的帖子。 ## %IGNOREINDEX 指定不用某一个或者某几个index。比如以下查询: ```sql select min(ps_supplycost) from %PARALLEL %IGNOREINDEX SQLUser.supplier.SUPPLIER_PK %IGNOREINDEX SQLUser.part.PART_PK %IGNOREINDEX SQLUser.nation.Nation_PK %IGNOREINDEX SQLUser.region.REGION_PK partsupp, supplier, nation, region where p_partkey = ps_partkey and s_suppkey = ps_suppkey and s_nationkey = n_nationkey and n_regionkey = r_regionkey and r_name = 'AFRICA' ... ``` *为什么要强制不用某些索引?* 一个是用在测试中,经常会比较不同索引的表现。比如你原来有个复合索引,它希望试试新创建的索引是不是更好, 那么很可能您需要告诉SQL引擎不要用以前的索引了。 还有就是您发现某个索引的使用没有让查询性能变好,强制不用它结果可以使用另一个索引,从而来得到更好的查询速度。 ## %ALLINDEX 用于测试所有可用的索引。 SQL引擎默认会在多个可用的索引中选中它判断最高效的,但这个判断不是总正确。加入%ALLINDEX会在生成查询计划前,测试所有可用的索引,以证实或者调整判断。 用到比较多的情况是有多个范围查询字句的情况。在Caché和早期IRIS版本中, 很多情况下, 使用%ALLINDEX会带来性能的提升, 尽管对所有可用索引做测试会有个额外开支. 比如以下的语句, ```sql SELECT TOP 5 ID, Name, Age, SSN FROM %ALLINDEX Sample.Person WHERE (:Name IS NULL or Name %STARTSWITH :Name) AND (:Age IS NULL or Age >= :Age) } ``` ## %NOINDEX 在最新版的IRIS文档中, 这个关键字已经去掉了。 我自己的测试中,在2022年后的IRIS中, 它其实已经不起作用了。 但在Caché中, 非常多的使用%NOINDEX的例子。 [Caché在线文档中的这段](https://docs.intersystems.com/latest/csp/docbook/DocBook.UI.Page.cls?KEY=GSQLOPT_optquery#GSQLOPT_optquery_altshowplans)是这么说的:当绝大多数数据被条件选中(或未被选中)时,这种方法最常用。在小于 () 条件语句下,使用 %NOINDEX 条件级提示通常是有益的。对于“等于”条件语句,使用 %NOINDEX 条件级提示没有任何好处。对于连接条件语句,不支持在 =* 和 *= WHERE 子句外部连接中使用 %NOINDEX;而在 ON 子句连接中使用 %NOINDEX。 这是文档上的例子: E.Age
文章
Jingwei Wang · 二月 15

使用嵌入式 Python 和 OpenAI API 在 IRIS 中进行数据标签

大型语言模型(例如 OpenAI 的 GPT-4)的发明和普及掀起了一波创新解决方案浪潮,这些解决方案可以利用大量非结构化数据,在此之前,人工处理这些数据是不切实际的,甚至是不可能的。此类应用程序可能包括数据检索(请参阅 Don Woodlock 的 ML301 课程,了解检索增强生成的精彩介绍)、情感分析,甚至完全自主的 AI 代理等! 在本文中,我想演示如何使用 IRIS 的嵌入式 Python 功能直接与 Python OpenAI 库交互,方法是构建一个简单的数据标记应用程序,该应用程序将自动为我们插入IRIS 表中的记录分配关键字。然后,这些关键字可用于搜索和分类数据,以及用于数据分析目的。我将使用客户对产品的评论作为示例用例。 先决条件 运行的IRIS实例 OpenAI API 密钥(您可以在此处创建) 配置好的开发环境(本文将使用VS Code ) Review类 让我们首先创建一个 ObjectScript 类,该类将定义客户评论的数据模型。为了简单起见,我们将只定义 4 个 %String 字段:客户姓名、产品名称、评论正文以及我们将生成的关键字。该类应该扩展%Persistent,以便我们可以将其对象保存到磁盘。 Class DataTagging.Review Extends %Persistent { Property Name As %String(MAXLEN = 50) [ Required ]; Property Product As %String(MAXLEN = 50) [ Required ]; Property ReviewBody As %String(MAXLEN = 300) [ Required ]; Property Keywords As %String(MAXLEN = 300) [ SqlComputed, SqlComputeOnChange = ReviewBody ]; } 由于我们希望在插入或更新 ReviewBody 属性时自动计算 Keywords属性,因此我将其标记为SqlComputed。您可以在此处了解有关计算值的更多信息。 KeywordsComputation方法 我们现在想要定义一种方法,用于根据ReviewBody计算Keywords。我们可以使用Embedded Python直接与官方的openai Python包进行交互。但首先,我们需要安装它。为此,请运行以下 shell 命令: <your-IRIS-installation-path>/bin/irispip install --target <your-IRIS-installation-path>/Mgr/python openai 我们现在可以使用 OpenAI 的聊天完成 API 来生成关键字: ClassMethod KeywordsComputation(cols As %Library.PropertyHelper) As %String [ Language = python ] { ''' This method is used to compute the value of the Keywords property by calling the OpenAI API to generate a list of keywords based on the review body. ''' from openai import OpenAI client = OpenAI( # Defaults to os.environ.get("OPENAI_API_KEY") api_key="<your-api-key>", ) # Set the prompt; use few-shot learning to give examples of the desired output user_prompt = "Generate a list of keywords that summarize the content of a customer review of a product. " \ + "Output a JSON array of strings.\n\n" \ + "Excellent watch. I got the blue version and love the color. The battery life could've been better though.\n\nKeywords:\n" \ + "[\"Color\", \"Battery\"]\n\n" \ + "Ordered the shoes. The delivery was quick and the quality of the material is terrific!.\n\nKeywords:\n" \ + "[\"Delivery\", \"Quality\", \"Material\"]\n\n" \ + cols.getfield("ReviewBody") + "\n\nKeywords:" # Call the OpenAI API to generate the keywords chat_completion = client.chat.completions.create( model="gpt-4", # Change this to use a different model messages=[ { "role": "user", "content": user_prompt } ], temperature=0.5, # Controls how "creative" the model is max_tokens=1024, # Controls the maximum number of tokens to generate ) # Return the array of keywords as a JSON string return chat_completion.choices[0].message.content } 请注意,在提示中,我首先指定了我希望 GPT-4 如何“生成总结产品客户评论内容的关键字列表”的一般说明,然后给出两个示例输入以及所需的输入输出。然后,我插入 cols.getfield("ReviewBody") 并以“Keywords:”一词结束提示,通过提供与我给出的示例格式相同的关键字来推动它完成句子。这是Few-Shot Prompting技术的一个简单示例。 为了演示的简单性,我选择将关键字存储为 JSON 字符串;在生产中存储它们的更好方法可能是DynamicArray ,但我将把它作为练习留给读者。 关键词生成 现在,我们可以通过管理门户使用以下 SQL 脚本向表中插入一行来测试我们的数据标记应用程序: INSERT INTO DataTagging.Review (Name, Product, ReviewBody) VALUES ('Ivan', 'BMW 330i', 'Solid car overall. Had some engine problems but got everything fixed under the warranty.') 如下所示,它自动为我们生成了四个关键字。做得好! 结论 总而言之,InterSystems IRIS 嵌入 Python 的能力在处理非结构化数据时提供了多种可能性。利用 OpenAI 的强大功能进行自动数据标记只是利用这一强大功能可以实现的目标之一。这可以减少人为错误并提高整体效率。
文章
姚 鑫 · 三月 27, 2021

第十三章 使用动态SQL(五)

# 第十三章 使用动态SQL(五) # 从结果集中返回特定的值 要从查询结果集中返回特定的值,必须一次一行遍历结果集。 要遍历结果集,请使用`%Next()`实例方法。 (对于单一值,结果对象中没有行,因此`%Next()`返回0,而不是错误。) 然后,可以使用`%Print()`方法显示整个当前行的结果,或者检索当前行的指定列的值。 `%Next()`方法获取查询结果中下一行的数据,并将该数据放入结果集对象的data属性中。 `%Next()`返回1,表示它位于查询结果中的某一行上。 `%Next()`返回0,表示它位于最后一行(结果集的末尾)之后。 每次调用`%Next()`返回1个增量`%ROWCOUNT`; 如果游标定位在最后一行之后(`%Next()`返回0),`%ROWCOUNT`表示结果集中的行数。 如果`SELECT`查询只返回聚合函数,每个`%Next()`设置`%ROWCOUNT=1`。 第一个`%Next()`返回1并设置`%SQLCODE=0`和`%ROWCOUNT=1`,即使表中没有数据; 任何随后的`%Next()`返回0,并设置`%SQLCODE=100`和`%ROWCOUNT=1`。 从结果集中获取一行后,可以使用以下任何一种方式显示该行的数据: - `rset.%Print()`返回查询结果集中当前行的所有数据值。 - `rset.%GetRow()`和`rset.getrows()`以编码列表结构的元素形式从查询结果集中返回一行的数据值。 - `rset.name`按查询结果集中的属性名称、字段名称、别名属性名称或别名字段名称返回数据值。 - `rset.%Get("fieldname")`通过字段名或别名从查询结果集中或存储的查询返回一个数据值。 - `rset.%GetData(n)`按列号从查询结果集中或存储的查询中返回一个数据值。 ## %Print()方法 `%Print()`实例方法从结果集中检索当前记录。默认情况下,`%Print()`在数据字段值之间插入空白空格分隔符。 `%Print()`不会在记录的第一个字段值之前或最后一个字段值之后插入空白; 它在记录的末尾发出一个行返回。 如果数据字段值已经包含空格,则将该字段值括在引号中,以将其与分隔符区分开来。 例如,如果`%Print()`返回城市名称,它将按如下方式返回它们: `"New York" Boston Atlanta "Los Angeles" "Salt Lake City" Washington`. 引用包含分隔符作为数据值一部分的字段值,即使从未使用过`%Print()`分隔符; 例如,如果结果集中只有一个字段。 可以选择指定`%Print()`参数,该参数提供在字段值之间放置的另一个定界符。指定其他定界符将覆盖包含空格的数据字符串的引用。此`%Print()`分隔符可以是一个或多个字符。它指定为带引号的字符串。通常,`%Print()`分隔符最好是在结果集数据中找不到的字符或字符串。但是,如果结果集中的字段值包含`%Print()`分隔符(或字符串),则该字段值将用引号引起来,以将其与分隔符区分开。 如果结果集中的字段值包含换行符,则该字段值将以引号引起来。 以下ObjectScript示例使用`%Print()`遍历查询结果集以显示每个结果集记录,并使用 `"^|^"` 定界符分隔值。请注意`%Print()`如何显示`FavoriteColors`字段中的数据,该字段是元素的编码列表: ```java /// d ##class(PHA.TEST.SQL).ROWCOUNTPrint() ClassMethod ROWCOUNTPrint() { SET q1="SELECT TOP 5 Name,DOB,Home_State,FavoriteColors " SET q2="FROM Sample.Person WHERE FavoriteColors IS NOT NULL" SET myquery = q1_q2 SET tStatement = ##class(%SQL.Statement).%New() SET qStatus = tStatement.%Prepare(myquery) IF qStatus'=1 { WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT } SET rset = tStatement.%Execute() WHILE rset.%Next() { WRITE "Row count ",rset.%ROWCOUNT,! DO rset.%Print("^|^") } WRITE !,"End of data" WRITE !,"Total row count=",rset.%ROWCOUNT } ``` ```java DHC-APP> d ##class(PHA.TEST.SQL).ROWCOUNTPrint() Row count 1 yaoxin^|^54536^|^WI^|^$lb("Red","Orange","Yellow") Row count 2 姚鑫^|^^|^^|^$lb("Red","Orange","Yellow","Green") Row count 3 姚鑫^|^^|^^|^$lb("Red","Orange","Yellow","Green","Green") Row count 4 Isaacs,Roberta Z.^|^^|^^|^$lb("Red","Orange","Yellow","Green","Yellow") Row count 5 Chadwick,Zelda S.^|^50066^|^WI^|^$lb("White") End of data Total row count=5 ``` 下面的示例显示如何将包含定界符的字段值括在引号中。在此示例中,大写字母`A`用作字段定界符;因此,任何包含大写字母A的字段值(名称,街道地址或州缩写)都将以引号引起来。 ```java /// d ##class(PHA.TEST.SQL).ROWCOUNTPrint2() ClassMethod ROWCOUNTPrint2() { SET myquery = "SELECT TOP 25 Name,Home_Street,Home_State,Age FROM Sample.Person" SET tStatement = ##class(%SQL.Statement).%New() SET qStatus = tStatement.%Prepare(myquery) IF qStatus'=1 { WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT } SET rset = tStatement.%Execute() WHILE rset.%Next() { DO rset.%Print("A") } WRITE !,"End of data" WRITE !,"Total row count=",rset.%ROWCOUNT } ``` ```java DHC-APP>d ##class(PHA.TEST.SQL).ROWCOUNTPrint2() yaoxinA889 Clinton DriveAWIA30 xiaoliAAA 姚鑫AAA7 姚鑫AAA7 姚鑫AAA43 姚鑫AAA 姚鑫AAA Isaacs,Roberta Z.AAA Chadwick,Zelda S.A9889 Clinton DriveAWIA43 Fives,James D.A2091 Washington BlvdANDA88 Vonnegut,Jose P.A3660 Main PlaceAWIA47 Chadbourne,Barb B.A1174 Second StreetA"VA"A93 "Quigley,Barb A."A"6501 Ash Avenue"AKYA73 ``` ## %GetRow()和%GetRows()方法 `%GetRow()`实例方法从结果集中检索当前行(记录),作为字段值元素的编码列表: ```java /// d ##class(PHA.TEST.SQL).ROWCOUNTPrint3() ClassMethod ROWCOUNTPrint3() { SET myquery = "SELECT TOP 17 %ID,Name,Age FROM Sample.Person" SET tStatement = ##class(%SQL.Statement).%New() SET qStatus = tStatement.%Prepare(myquery) IF qStatus'=1 { WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT } SET rset = tStatement.%Execute() FOR { SET x=rset.%GetRow(.row,.status) IF x=1 { WRITE $LISTTOSTRING(row," | "),! } ELSE { WRITE !,"End of data" WRITE !,"Total row count=",rset.%ROWCOUNT RETURN } } } ``` `%GetRows()`实例方法从结果集中检索指定大小的一组行(记录)。每行作为字段值元素的编码列表返回。 下面的示例返回结果集中的第1、6和11行。在此示例中,`%GetRows()`第一个参数(5)指定`%GetRows()`应该检索五行的连续组。如果成功检索到一组五行,`%GetRows()`将返回1。 `.rows`参数通过引用传递这五行的下标数组,因此,`rows(1)`返回每五组中的第一行:第1、6和11行。指定`rows(2)`将返回第2、7行和12。 ```java /// d ##class(PHA.TEST.SQL).ROWCOUNTPrint4() ClassMethod ROWCOUNTPrint4() { SET myquery = "SELECT TOP 17 %ID,Name,Age FROM Sample.Person" SET tStatement = ##class(%SQL.Statement).%New() SET qStatus = tStatement.%Prepare(myquery) IF qStatus'=1 { WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT } SET rset = tStatement.%Execute() FOR { SET x=rset.%GetRows(5,.rows,.status) IF x=1 { WRITE $LISTTOSTRING(rows(1)," | "),! } ELSE { WRITE !,"End of data" WRITE !,"Total row count=",rset.%ROWCOUNT RETURN } } } ``` 可以使用`ZWRITE rows`命令返回检索到的数组中的所有下标,而不是按下标检索单个行。请注意,上面的示例ZWRITE行不会返回结果集中的第16行和第17行,因为在检索到最后一组五行之后,这些行是余数。 ## rset.name属性 当InterSystems IRIS生成结果集时,它将创建一个结果集类,其中包含一个与该结果集中的每个字段名称和字段名称别名相对应的唯一属性。 可以使用`rset.name`属性按属性名称,字段名称,属性名称别名或字段名称别名返回数据值。 - 属性名称:如果未定义字段别名,则将字段属性名称指定为`rset.PropName`。结果集字段属性名称取自表定义类中的相应属性名称。 - 字段名称:如果没有定义字段别名,请将字段名称(或属性名称)指定为`rset。“fieldname”`。这是表定义中指定的`SQLFIELDNAME`。 Intersystems Iris使用此字段名称来查找相应的属性名称。在许多情况下,属性名称和字段名称(`SQLFieldName`)是相同的。 - 别名属性名称:如果定义了字段别名,则将别名属性名称指定为`rset.AliasProp`。别名属性名称是根据`SELECT`语句中的列名称别名生成的。不能为具有已定义别名的字段指定字段属性名称。 - 别名:如果定义了字段别名,则将此别名(或别名属性名称)指定为`rset。“ alias”`。这是`SELECT`语句中的列名别名。您不能为具有已定义别名的字段指定字段名称。 - 集合,表达式或子查询:InterSystems IRIS为这些选择项分配一个字段名称`Aggregate_n`,`Expression_n`或`Subquery_n`(其中整数`n`对应于查询中指定的选择项列表的顺序)。可以使用字段名称(`rset。“ SubQuery_7”`不区分大小写),相应的属性名称(`rset.Subquery7`区分大小写)或用户定义的字段名称别名来检索这些select-item值。也可以只使用`rset。%GetData(n)`指定选择项的序列号。 指定属性名称时,必须使用正确的字母大小写;指定字段名称时,不需要正确的字母大小写。 使用属性名称对`rset.name`的调用具有以下后果: - 字母大小写:属性名称区分大小写。字段名称不区分大小写。 Dynamic SQL可以自动解决指定字段或别名与相应属性名称之间的字母大小写差异。但是,解决字母大小写需要时间。为了最大限度地提高性能,应该指定属性名称或别名的确切字母大小写。 - 非字母数字字符:属性名称只能包含字母数字字符(起始的`%`字符除外)。如果相应的SQL字段名称或字段名称别名包含非字母数字字符(例如`Last_Name`),则可以执行以下任一操作: - 指定用引号分隔的字段名称。例如,`rset。“ Last_Name”`)。分隔符的这种使用不需要启用分隔符。执行大写字母解析。 - 指定相应的属性名称,以消除非字母数字字符。例如,`rset.LastName`(或`rset。“ LastName”`)。必须为属性名称指定正确的字母大小写。 - `%`属性名称:通常,以`%`字符开头的属性名称保留供系统使用。如果字段属性名称或别名以`%`字符开头,并且该名称与系统定义的属性冲突,则返回系统定义的属性。例如,对于`SELECT Notes AS%Message`,调用`rset。%Message`将不返回`Notes`字段值。它返回为语句结果类定义的`%Message`属性。可以使用`rset。%Get(“%Message”)`返回字段值。 - 列别名:如果指定了别名,则Dynamic SQL始终匹配该别名,而不匹配字段名称或字段属性名称。例如,对于`SELECT Name AS Last_Name`,只能使用`rset.LastName`或`rset。“ Last_Name”`来检索数据,而不能使用`rset.Name`。 - 重复名称:如果名称解析为相同的属性名称,则它们是重复的。重复名称可以是对表中同一字段的多个引用,对表中不同字段的别名引用或对不同表中字段的引用。例如,`SELECT p.DOB,e.DOB`指定两个重复的名称,即使这些名称引用了不同表中的字段。 如果`SELECT`语句包含相同字段名称或字段名称别名的多个实例,则`rset.propname`或`rset。“fieldname”`始终返回`SELECT`语句中指定的第一个。例如,对于`SELECT C.NAME,P.NAME`来自`Sample.person as p,sample.company`使用`rset.name`检索公司名称字段数据;选择`C.Name,P.Name`作为来自`Sample.person`的名称,`As P,Sample.com`本文使用`RSET。“name”`还检索公司名称字段数据。如果查询中存在重复的名称字段,则字段名称(名称)的最后一个字符由字符(或字符)替换为创建唯一属性名称。因此,查询中的重复名称字段名称具有相应的唯一属性名称,以`NAM0`(第一个重复)通过`NAM9`开始,并通过`NAMZ`继续大写字母`NAMA`。 对于使用`%Prepare()`准备的用户指定的查询,可以单独使用属性名称。对于使用`%PrepareClassQuery()`准备的存储查询,必须使用`%Get(“ fieldname”)`方法。 下面的示例返回由属性名称指定的三个字段的值:两个属性值分别由属性名称和第三个属性值由别名属性名称。在这些情况下,指定的属性名称与字段名称或字段别名相同: ```java /// d ##class(PHA.TEST.SQL).PropSQL() ClassMethod PropSQL() { SET myquery = "SELECT TOP 5 Name,DOB AS bdate,FavoriteColors FROM Sample.Person" SET tStatement = ##class(%SQL.Statement).%New(1) SET qStatus = tStatement.%Prepare(myquery) IF qStatus'=1 { WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT } SET rset = tStatement.%Execute() WHILE rset.%Next() { WRITE "Row count ",rset.%ROWCOUNT,! WRITE rset.Name WRITE " prefers ",rset.FavoriteColors WRITE " birth date ",rset.bdate,!! } WRITE !,"End of data" WRITE !,"Total row count=",rset.%ROWCOUNT } ``` ```java DHC-APP>d ##class(PHA.TEST.SQL).PropSQL() Row count 1 yaoxin prefers Red,Orange,Yellow birth date 1990-04-25 Row count 2 xiaoli prefers birth date Row count 3 姚鑫 prefers birth date 2014-01-02 Row count 4 姚鑫 prefers birth date 2014-01-02 Row count 5 姚鑫 prefers birth date 1978-01-28 End of data Total row count=5 ``` 在上面的示例中,返回的字段之一是`FavoriteColors`字段,其中包含`%List`数据。若要显示此数据,`%New(1)`类方法将`%SelectMode`属性参数设置为1(ODBC),从而导致该程序将`%List`数据显示为逗号分隔的字符串,并以ODBC格式显示出生日期: 下面的示例返回`Home_State`字段。因为属性名称不能包含下划线字符,所以本示例指定用引号`(“ Home_State”)`分隔的字段名称`(SqlFieldName)`。还可以指定不带引号的相应生成的属性名称`(HomeState)`。请注意,定界字段名称`(“ Home_State”)`不区分大小写,但是生成的属性名称`(HomeState)`是区分大小写的: ```java /// d ##class(PHA.TEST.SQL).PropSQL1() ClassMethod PropSQL1() { SET myquery = "SELECT TOP 5 Name,Home_State FROM Sample.Person" SET tStatement = ##class(%SQL.Statement).%New(2) SET qStatus = tStatement.%Prepare(myquery) IF qStatus'=1 {WRITE "%Prepare failed:" DO $System.Status.DisplayError(qStatus) QUIT} SET rset = tStatement.%Execute() WHILE rset.%Next() { WRITE "Row count ",rset.%ROWCOUNT,! WRITE rset.Name WRITE " lives in ",rset."Home_State",! } WRITE !,"End of data" WRITE !,"Total row count=",rset.%ROWCOUNT } ``` ```java DHC-APP>d ##class(PHA.TEST.SQL).PropSQL1() Row count 1 yaoxin lives in WI Row count 2 xiaoli lives in Row count 3 姚鑫 lives in Row count 4 姚鑫 lives in Row count 5 姚鑫 lives in End of data Total row count=5 ``` %GetRows 这个方法在IRIS 2019里有吗?
文章
Jingwei Wang · 九月 16, 2022

Python应用程序连接到InterSystemsIRIS数据库 - 使用 DB-API

连接前准备: Python 开发环境 DB-API驱动:irispython wheel 文件 Connection String 步骤: 安装irispython wheel 文件 pip install intersystems_irispython-3.2.0-py3-none-any.whl Connection String:其中import iris 用来导入iris, connection = iris.connect是connection string。connection.close()用来断开连接。 import iris def main(): connection_string = "localhost:1972/USER" username = "SQLAdmin" password = "deployment-password" connection = iris.connect(connection_string, username, password) # when finished, use the line below to close the connection # connection.close() if __name__ == "__main__": main()
文章
Kelly Huang · 九月 3, 2023

独立模式下 EMPI 的安装和适配 - FHIR之转换和摄取

大家好。 在上一篇文章中,我们了解了如何配置 EMPI 来接收 FHIR 消息。为此,我们安装了 InterSystems 提供的 FHIR 适配器,该适配器配置了一个可以向其发送 FHIR 消息的 REST 端点。然后,我们将获取消息并将其转换为 %String,我们将通过 TCP 将其发送到 HSPIDATA 命名空间中配置的 EMPI 的输出。 好吧,是时候看看我们如何检索消息、将其转换回 %DynamicObject 并将其解析为 EMPI 用来存储信息的类。 TCP消息接收 正如我们所指出的,从配置了 FHIR 资源接收的生产中,我们已将消息发送到我们有业务服务侦听的特定 TCP 端口,在我们的例子中,该业务服务将是一个简单的EnsLib.TCP。 PassthroughService的目标是捕获消息并将其转发到业务流程,我们将在其中执行所需的数据转换。 这里有我们的商业服务: 这是它的基本配置: FHIR 消息的转变 正如你所看到的,我们只配置了通过 TCP 接收消息的端口以及我们将向其发送消息的组件,在我们的例子中我们将其称为 Local.BP.FHIRProcess,让我们看一下说类来看看我们如何从 FHIR 资源中检索信息: Class Local.BP.FHIRProcess Extends Ens.BusinessProcess [ ClassType = persistent ] { Method OnRequest(pRequest As Ens.StreamContainer, Output pResponse As Ens.Response) As %Status { set tDynObj = {}. %FromJSON (pRequest.Stream) If (tDynObj '= "" ) { set hubRequest = ##class (HS.Message.AddUpdateHubRequest). %New () // Create AddUpdateHub Message // Name, sex, DOB set givenIter = tDynObj.name. %Get ( 0 ).given. %GetIterator () while givenIter. %GetNext (, .givenName){ if (hubRequest.FirstName '= "" ) { Set hubRequest.FirstName=givenName } else { Set hubRequest.FirstName=hubRequest.FirstName_ " " _givenName } } Set hubRequest.FirstName=tDynObj.name. %Get ( 0 ).given. %Get ( 0 ) Set hubRequest.LastName=tDynObj.name. %Get ( 0 ).family Set hubRequest.Sex=tDynObj.gender Set hubRequest.DOB=hubRequest.DOBDisplayToLogical(tDynObj.birthDate) // Inserts full birth name information for the patient set nameIter = tDynObj.name. %GetIterator () while nameIter. %GetNext (, .name){ Set tName = ##class (HS.Types.PersonName). %New () if (name.prefix '= "" ) { Set tName.Prefix = name.prefix. %Get ( 0 ) } Set tName.Given = name.given. %Get ( 0 ) Set tName.Middle = "" Set tName.Family = name.family Set tName.Suffix = "" Set tName.Type= ^Ens .LookupTable( "TypeOfName" ,name. use ) Do hubRequest.Names.Insert(tName) } set identIter = tDynObj.identifier. %GetIterator () while identIter. %GetNext (, .identifier){ if (identifier.type'= "" ){ if (identifier.type.coding. %Get ( 0 ).code = "MR" ) { Set hubRequest.MRN = identifier.value Set hubRequest.AssigningAuthority = ^Ens .LookupTable( "hospital" ,identifier.system) Set hubRequest.Facility = ^Ens .LookupTable( "hospital" ,identifier.system) } elseif (identifier.type.coding. %Get ( 0 ).code = "SS" ) { Set hubRequest.SSN = identifier.value } else { Set tIdent= ##class (HS.Types.Identifier). %New () Set tIdent.Root = identifier.system // refers to an Assigning Authority entry in the OID Registry Set tIdent.Extension = identifier.value Set tIdent.AssigningAuthorityName = identifier.system Set tIdent. Use = identifier.type.coding. %Get ( 0 ).code Do hubRequest.Identifiers.Insert(tIdent) } } } // Address set addressIter = tDynObj.address. %GetIterator () while addressIter. %GetNext (, .address){ Set addr= ##class (HS.Types.Address). %New () Set addr.City=address.city Set addr.State=address.state Set addr.Country=address.country Set addr.StreetLine=address.line. %Get ( 0 ) Do hubRequest.Addresses.Insert(addr) } //Telephone set identTel = tDynObj.telecom. %GetIterator () while identTel. %GetNext (, .telecom){ if (telecom.system = "phone" ) { Set tel= ##class (HS.Types.Telecom). %New () Set tel.PhoneNumber=telecom.value Do hubRequest.Telecoms.Insert(tel) } } } Set tSC = ..SendRequestSync ( "HS.Hub.MPI.Manager" , hubRequest, .pResponse) Quit tSC } Storage Default { <Type> %Storage.Persistent </Type> } } 让我们更详细地看看我们正在做什么: 首先我们收到了业务服务发来的消息: Method OnRequest(pRequest As Ens.StreamContainer, Output pResponse As Ens.Response) As %Status { set tDynObj = {}. %FromJSON (pRequest.Stream) 正如我们在 OnRequest 方法的签名中看到的,输入消息对应于Ens.StreamContainer类型的类。 %String 类型消息的这种转换已在业务服务中进行。在该方法的第一行中,我们要做的是检索在 pRequest 变量中作为 Stream 找到的消息。然后,我们使用 %FromJSON 语句将其转换为 %DynamicObject。 通过将消息映射到动态对象,我们将能够访问已发送的 FHIR 资源的每个字段: set tDynObj = {}. %FromJSON (pRequest.Stream) If (tDynObj '= "" ) { set hubRequest = ##class (HS.Message.AddUpdateHubRequest). %New () // Create AddUpdateHub Message // Name, sex, DOB set givenIter = tDynObj.name. %Get ( 0 ).given. %GetIterator () while givenIter. %GetNext (, .givenName){ if (hubRequest.FirstName '= "" ) { Set hubRequest.FirstName=givenName } else { Set hubRequest.FirstName=hubRequest.FirstName_ " " _givenName } } Set hubRequest.FirstName=tDynObj.name. %Get ( 0 ).given. %Get ( 0 ) Set hubRequest.LastName=tDynObj.name. %Get ( 0 ).family Set hubRequest.Sex=tDynObj.gender Set hubRequest.DOB=hubRequest.DOBDisplayToLogical(tDynObj.birthDate) 在此片段中,我们看到如何创建HS.Message.AddUpdateHubRequest类的对象,该对象是我们将发送到负责在 EMPI 内执行相应操作的业务操作 HS.Hub.MPI.Manager 的对象,无论是是创建新患者或更新它,以及将其与 EMPI 中已有的其他患者可能存在的可能匹配项链接起来。 下一步是使用从业务服务接收到的数据填充新对象。正如您所看到的,我们所做的就是从刚刚创建的动态对象的不同字段中检索数据。动态对象的格式与 HL7 FHIR 为患者资源定义的格式完全对应,您可以直接在HL7 FHIR 网页上查看示例 对于我们的示例,我们从 HL7 FHIR 页面本身提供的列表中选择了该患者: { "resourceType" : "Patient" , "id" : "example" , "text" : { "status" : "generated" , "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\">\n\t\t\t<table>\n\t\t\t\t<tbody>\n\t\t\t\t\t<tr>\n\t\t\t\t\t\t<td>Name</td>\n\t\t\t\t\t\t<td>Peter James \n <b>Chalmers</b> ("Jim")\n </td>\n\t\t\t\t\t</tr>\n\t\t\t\t\t<tr>\n\t\t\t\t\t\t<td>Address</td>\n\t\t\t\t\t\t<td>534 Erewhon, Pleasantville, Vic, 3999</td>\n\t\t\t\t\t</tr>\n\t\t\t\t\t<tr>\n\t\t\t\t\t\t<td>Contacts</td>\n\t\t\t\t\t\t<td>Home: unknown. Work: (03) 5555 6473</td>\n\t\t\t\t\t</tr>\n\t\t\t\t\t<tr>\n\t\t\t\t\t\t<td>Id</td>\n\t\t\t\t\t\t<td>MRN: 12345 (Acme Healthcare)</td>\n\t\t\t\t\t</tr>\n\t\t\t\t</tbody>\n\t\t\t</table>\n\t\t</div>" }, "identifier" : [ { "use" : "usual" , "type" : { "coding" : [ { "system" : "http://terminology.hl7.org/CodeSystem/v2-0203" , "code" : "MR" } ] }, "system" : "urn:oid:1.2.36.146.595.217.0.1" , "value" : "12345" , "period" : { "start" : "2001-05-06" }, "assigner" : { "display" : "Acme Healthcare" } } ], "active" : true , "name" : [ { "use" : "official" , "family" : "Chalmers" , "given" : [ "Peter" , "James" ] }, { "use" : "usual" , "given" : [ "Jim" ] }, { "use" : "maiden" , "family" : "Windsor" , "given" : [ "Peter" , "James" ], "period" : { "end" : "2002" } } ], "telecom" : [ { "use" : "home" }, { "system" : "phone" , "value" : "(03) 5555 6473" , "use" : "work" , "rank" : 1 }, { "system" : "phone" , "value" : "(03) 3410 5613" , "use" : "mobile" , "rank" : 2 }, { "system" : "phone" , "value" : "(03) 5555 8834" , "use" : "old" , "period" : { "end" : "2014" } } ], "gender" : "male" , "birthDate" : "1974-12-25" , "_birthDate" : { "extension" : [ { "url" : "http://hl7.org/fhir/StructureDefinition/patient-birthTime" , "valueDateTime" : "1974-12-25T14:35:45-05:00" } ] }, "deceasedBoolean" : false , "address" : [ { "use" : "home" , "type" : "both" , "text" : "534 Erewhon St PeasantVille, Rainbow, Vic 3999" , "line" : [ "534 Erewhon St" ], "city" : "PleasantVille" , "district" : "Rainbow" , "state" : "Vic" , "postalCode" : "3999" , "period" : { "start" : "1974-12-25" } } ], "contact" : [ { "relationship" : [ { "coding" : [ { "system" : "http://terminology.hl7.org/CodeSystem/v2-0131" , "code" : "N" } ] } ], "name" : { "family" : "du Marché" , "_family" : { "extension" : [ { "url" : "http://hl7.org/fhir/StructureDefinition/humanname-own-prefix" , "valueString" : "VV" } ] }, "given" : [ "Bénédicte" ] }, "telecom" : [ { "system" : "phone" , "value" : "+33 (237) 998327" } ], "address" : { "use" : "home" , "type" : "both" , "line" : [ "534 Erewhon St" ], "city" : "PleasantVille" , "district" : "Rainbow" , "state" : "Vic" , "postalCode" : "3999" , "period" : { "start" : "1974-12-25" } }, "gender" : "female" , "period" : { "start" : "2012" } } ], "managingOrganization" : { "reference" : "Organization/1" } } 首先,我们创建了 2 个查找表,用于映射姓名类型和分配医疗记录号 (MR) 的权限,第一个与 EMPI 管理的类型兼容,第二个用于识别分配权限生成标识符: Set tName.Type= ^Ens .LookupTable( "TypeOfName" ,name. use ) Set hubRequest.AssigningAuthority = ^Ens .LookupTable( "hospital" ,identifier.system) Set hubRequest.Facility = ^Ens .LookupTable( "hospital" ,identifier.system) 启动测试消息 完美,让我们针对我们在上一篇文章中定义的端点启动 FHIR 消息: 正如您所看到的,我们收到了 200 响应,这仅意味着 EMPI 已正确接收到消息,现在让我们看看在我们的生产中生成的跟踪: 这里我们有我们的病人,您可以看到转换已成功执行,并且 FHIR 消息中报告的所有字段都已正确分配。可以看到,一条IDUpdateNotificationRequest通知消息已经生成了。当在系统中执行创建或更新患者的操作时,会生成此类通知。 很好,让我们通过按姓名搜索患者来检查患者是否在我们的系统中正确注册: 答对了!让我们更详细地看看我们亲爱的Peter的数据: 相当完美!我们的 EMPI 中已经包含了有关患者的所有必要信息。正如您所看到的,该机制非常简单,让我们回顾一下我们执行的步骤: 我们已将 InterSystems 提供的 FHIR 适配器工具安装在配置为支持互操作性的命名空间(与 EMPI 独立安装生成的命名空间不同的命名空间,在我的例子中称为 WEBINAR)中。 我们在此命名空间中创建了一个业务操作,它将接收到的HS.FHIRServer.Interop.Request类型的消息转换为 %String,并将其发送到在 EMPI 命名空间 (HSPIDATA) 的生产中配置的业务服务。 接下来,我们添加了EnsLib.TCP.PassthroughService类的业务服务,该类接收从 WEBINAR 命名空间的生成发送的消息并重定向到业务流程Local.BP.FHIRProcess 。 在 BP Local.BP.FHIRProcess 中,我们已将接收到的 Stream 转换为HS.Message.AddUpdateHubRequest类型的对象,并将其发送到业务运营HS.Hub.MPI.Manager ,该管理器将负责将其注册到我们的EMPI。 正如您所看到的,EMPI 功能与 IRIS 集成引擎提供的功能的结合使我们能够使用几乎任何类型的技术。 我希望这篇文章对您有用。如果您有任何问题或建议,您已经知道,请发表评论,我将很乐意为您解答。 原贴作者:@Luis Angel
文章
Nicky Zhu · 十月 10

FHIRValidation - 用IRIS验证你自己的FHIR IG

本演示程序用于展示如何采用自定义FHIR profile来验证数据合规性。自定义FHIR实施指南基于[FHIR R4版本](https://hl7.org/fhir/R4/index.html)开发,在本例中实现了对[Organization](https://hl7.org/fhir/R4/organization.html)资源的扩展并用于验证数据的合规性。 # 安装 1. 通过Git clone下载本项目。 2. 执行docker-compose up -d构建并启动容器,初次执行时需执行需10~15分钟(视配置变化)。将构建InterSystems IRIS for Health镜像,安装FHIR服务器,导入自定义FHIR规范,使自定义FHIR 规范可用于验证数据。 3. 在Postman中导入TestCases中的测试用例文件,查看各类FHIR约束的测试效果 4. 容器启动后可查看[自定义IG](http://localhost:52880/csp/FullIG/index.html)内容 # 项目代码结构 ``` FHIRValidation ├─ ExampleIG │ ├─ ig.ini │ ├─ input │ │ ├─ fsh │ │ │ ├─ alias.fsh │ │ │ ├─ codesystems.fsh │ │ │ ├─ organization.fsh │ │ │ └─ valuesets.fsh │ │ └─ pagecontent │ │ └─ index.md │ └─ sushi-config.yaml ├─ README.md ├─ README_zh.md ├─ TestCases │ └─ FHIR Profile-based Validation testcases.postman_collection.json ├─ docker-compose.yml └─ image-iris ├─ Dockerfile └─ src ├─ FullIG ├─ IGPackages │ ├─ hl7.fhir.uv.extensions.r4#5.1.0.tgz │ ├─ hl7.terminology.r4#6.0.2.tgz │ └─ package.tgz └─ init └─ init.sh ``` ## ExampleIG 该子目录下的所有文件为本项目所采用的自定义FHIR规范[SUSHI](https://fshschool.org/docs/sushi/)源码,供用户定义FHIR规约时参考使用。 ## TestCases 该子目录下存放基于FHIR REST API的测试用例脚本,需导入到Postman中使用 ## image-iris 该子目录下存放nterSystems IRIS for Health镜像所需的文件,其中: └─ src ├─ FullIG 该目录中存放SUSHI生成的自定义FHIR IG ├─ IGPackages 该目录中存放自定义FHIR IG的 [package](#fhir-package) 文件 └─ init 该目录中存放IRIS的Docker镜像初始化脚本 # FHIR package简介 HL7组织推荐使用实施指南([Implementation Guild](https://build.fhir.org/ig/FHIR/ig-guidance/))来解释如何使用FHIR规范。除用于开发人员阅读的说明(如html)外,实施指南中通常也包括可直接被机器读取和应用的工件(artifacts),可被用于驱动代码生成和数据验证等任务。 FHIR实施指南采用[NPM Package](https://docs.npmjs.com/cli/v8/configuring-npm/package-json)规范管理依赖。指南涉及的所有StructureDefinition,ValueSet等资源将被打包在一块,形成可被FHIR Server用于读取规范,生成客户端代码或执行数据质量校验的资源包。 通过SUSHI工具生成的实施指南中就包含若干package文件。如本例中,image-iris/src/IGPackages/package.tgz即为生成的package包,可被IRIS FHIR Server直接导入使用。应当注意到的是,除核心资源包(如[hl7.fhir.r4.core](https://hl7.org/fhir/R4/downloads.html))外,完整的FHIR规范还需要引用术语、扩展等额外的资源包。 目前FHIR规范引用机制的文档尚不完善。如基于R4版的FHIR规范除引用hl7.fhir.r4.core外,还需引用[hl7.fhir.uv.extensions.r4#5.1.0](https://simplifier.net/packages/hl7.fhir.uv.extensions.r4/5.1.0)与[hl7.terminology.r4#6.0.2](https://terminology.hl7.org/downloads.html),但这些引用关系在[R5版本](https://hl7.org/fhir/packages.html)中方有记录,在R4版文档中并未完整声明,需开发者在开发过程中自行补充。 在本例中这些包已下载在image-iris/src/IGPackages文件夹下,将作为依赖在自定义FHIR实施指南之前加载。 # FHIR validation简介 参见FHIR规范[Validating Resources](https://hl7.org/fhir/R4/validation.html)一节。FHIR规范已经设计了对数据结构、属性基数、值域、代码绑定和约束等一系列机制在内的数据质量校验机制。HL7组织在FHIR规范中并未强制要求遵循何种强度的质量控制,但建议采用[宽进严出](https://hl7.org/fhir/R4/validation.html#correct-use)的原则处理FHIR数据。 对于保存FHIR资源的FHIR存储库而言,保障FHIR资源的数据质量是使医疗行业具有价值,保障医疗行为安全性的前提条件。因此,在构建基于FHIR存储的数据共享交换方案时,即使不得不保存不满足数据质量要求的数据,也应对其进行校验,标识不符合项,推动数据治理活动的进行,从而保障医疗安全和数据消费者的利益。 在FHIR规范指出的多种数据校验方式中,FHIR Validator和[FHIR操作](https://hl7.org/fhir/R4/resource-operation-validate.html)对数据质量校验的覆盖最为全面。 本例将使用InterSystems IRIS for Health所提供的`$`validate操作,通过profile参数对尚未保存的FHIR数据进行校验。使用者也可修改测试用例,构建HTTP POST参数,对存量FHIR资源进行校验。 还应当注意的是,$validate操作如被正确调用,将通过Http 200返回校验结果,如有不符合项,将在返回的OperationOutcome资源中包裹错误信息,而不通过Http代码标识错误。 # 对FHIR的扩展 在本例中基于FHIR R4对Organization资源进行了如下扩展: ## 1. 修改language的绑定强度 将机构主要语言的绑定强度修改为required ## 2. active字段基数从0..1改为1..1 从而使得数据的状态成为必填字段,有且只有一个元素 ## 3. name字段基数从0..1改为1..1 组织机构名称成为必填字段,有且只有一个元素。参考我国医院除医院名称外,如果具备急救中心、胸痛中心等牌照,还可能具有多个名称。但因注意到,这些牌照通常标识了医疗机构提供的服务能力,而非在组织机构注册系统中具备的法定名称,且此类牌照生命周期与医疗机构自身的生命周期并不一致。因此,从牌照获得的名称宜视为该医疗机构的服务能力而非机构的唯一名称。在FHIR中,通过服务能力获得的名称可通过资源HealthcareService提供,该资源与Organization资源间可建立多对一的引用关系,更适合用来表达上述概念。 ## 4. 增加医疗机构的组织机构类型 根据中国国家标准GB/T 20091-2021 组织机构类型,分别增加了CodeSystem organizationtype-code-system和ValueSet organizationtype-vs,并通过Extension向Organization资源中添加了扩展mdm-organizationTypeExtension,从而使得该资源可用于表示表示标识中国组织机构类型。 该扩展通过对Extension切片实现,且基数为1..1,即医疗机构资源必须具有组织机构类型元素。 ## 5. 约束医疗机构证件号码 FHIR基础标准并未纳入中国组织机构统一社会信用代码的证件类型,为此增加了CodeSystem cs-identifierType-code-system,并对Identifier按其类型进行了切片,使之必须可以表达社会信用代码。且社会信用代码的格式遵循以下约束: 1. identifier.use必须取值为official,即正式/官方用途 2. identifier.type必须遵循cs-identifierType-code-system要求,system必须为该codesystem的uri,code必须为“USCC” 3. identifier.value必须遵循自定义约束uscc-length-18,该字段长度必须为18位,其中前17位必须为数字,最后1位必须为数字或字母 # 测试用例列表 ## 1. Without profile - All OK 未声明资源对应的profile,因此FHIR Server将不对资源中各属性的值进行校验,仅返回All OK。 ## 2. Unknow field 在资源中加入了未被定义的属性isNational,因此校验引擎返回了Unrecognized element错误。 ## 3. Wrong cardinality - less 在本IG中,修改了Organization资源name属性的基数为1..1,即应有且仅有一个组织机构名称。本测试用例未填写名称,因此数据校验失败。 另外,可以观察到Identifier.type经过扩展,加入了统一社会信用代码作为标识符类型,FHIR R4规范里并不包含这个值,但该字段的代码绑定强度仅为example,不强制约束。因此校验引擎返回了information级的值域代码不符合信息而没有报错。 ## 4. Binding strength 在本IG中,组织机构的language属性的代码绑定强度改为了required,则该字段值域必须符合http://hl7.org/fhir/ValueSet/languages,因此,当该字段取值为wrong language时,因不在required值域中,将导致error级错误 ## 5. Wrong value 在本IG中,组织机构类型的值域来自于organizationtype-code-system,因此,当类型为mdm-organizationTypeExtension的extension元素中code的值为“999”,不在值域中时,将导致error级错误 ## 6. Failing invariant 在本IG中,组织机构的社会信用代码必须遵循自定义约束uscc-length-18(该字段长度必须为18位,其中前17位必须为数字,最后1位必须为数字或字母),因此,当其末位为字符“%”时,违反该约束,将导致error级错误 ## 7. Failing profile 对于一个资源定义的一个profile包含了多个约束,因此,在校验时所有不满足profile的问题都将被检出,例如本例中: 1. 错误的language代码 2. 错误的组织机构类型 3. 缺少name字段 可见上述问题都被检出