服务配置:YAML结构

本文属使用Prisma构建GraphQL服务系列。

概述

服务定义文件prisma.yml具有以下根属性：

• datamodel(必须)：数据库模型，关系，枚举和其他类型的类型定义。
• endpoint：Prisma API的HTTP端点。可以省略以提示CLI部署向导。
• secret：保护API端点。
• schema：Prism API的GraphQL schema的路径。
• subscriptions：订阅webhooks的配置。
• seed：指向包含突变的种子数据文件。
• custom：用于提供可在prisma.yml其他地方引用的变量。

prisma.yml的精确结构是使用JSON Schema定义的。可以在这里找到相应的Schema定义。

datamodel(必须)

datamodel指向包含用GraphQL SDL编写的类型定义的一个或多个.graphql文件。如果提供多个​​文件，CLI将在部署时简单地拼接它们的内容。

类型

datamodel属性为一个字符串或一个字符串列表。

示例

数据模型在一个名为types.graphql的文件中定义。

datamodel: types.graphql

数据模型在两个名为types.graphql和enums.graphl的文件中定义。部署时，两个文件的内容将通过CLI连接。

datamodel:
  - types.graphql
  - enums.graphql

endpoint(可选)

Prisma API的HTTP端点由以下组件组成：

• Prisma server：承载您的Prisma API的服务器。
• Workspace(仅Prisma Cloud)：您通过Prisma Cloud配置的Workspace的名称。
• Service name：Prism API的描述性名称。
• Stage: cluster的开发阶段（例如，dev，staging，prod）。

请注意，endpoint实际上需要部署您的Prisma API。但是，如果您在运行prisma deploy之前没有在prisma.yml中指定它，CLI将使用向导来提示您几个问题，并将端点添加到prisma.yml中。

类型

endpoint属性为一个字符串。

示例

1.以下示例端点对此信息进行编码：

• Prisma server：localhost:4466意味着您使用Docker在本地计算机上部署API（在端口4466上）。
• Service name：default。
• Stage：default。

注意：当Service name和Stage都设置为default时，它们可以省略，并由Prisma推断。这意味着如下示例端点相当于：http:// localhost:4466/

endpoint: http://localhost:4466/default/default

2.以下示例端点对此信息进行编码：

• Prisma server：eu1.prisma.sh意味着您使用Prisma Sandbox 部署Prisma API。
• ** Workspace**：public-helixgoose-752是一个随机生成的字符串，用于标识Sandbox的Prisma Cloud工作区。
• Service name：myservice。
• Stage：dev。

endpoint: https://eu1.prisma.sh/public-helixgoose-752/myservice/dev

3.以下示例端点对此信息进行编码：

• Prisma server：http://my-pr-Publi-1GXX8QUZU3T89-413349553.us-east-1.elb.amazonaws.com意味着您正在使用自定义服务器来部署您的Prism API。
• ** Workspace**：public-helixgoose-752是一个随机生成的字符串，用于标识Sandbox的Prisma Cloud工作区。
• Service name：cat-pictures。
• Stage：prod。

endpoint: http://my-pr-Publi-1GXX8QUZU3T89-413349553.us-east-1.elb.amazonaws.com/cat-pictures/prod

secret(可选)

secret用于生成（或签名）认证令牌（JWT）。其中一个身份验证令牌需要附加到HTTP请求（位于Authorization头字段中）。secret必须遵守这些要求：

• 必须是utf8编码的
• 不得包含空格
• 最长不得超过256个字符

请注意，可以在此字符串中编码多个secret，从而实现平滑的secret旋转。

在这里阅读更多关于数据库认证。

警告：如果Prisma API没有secret部署，它不需要验证。这意味着每个访问端点的人都可以发送任意查询和突变，因此可以读取和写入数据库！

类型

secret属性为一个字符串（不是字符串列表）。如果你想指定多个secret，用逗号分隔（空格被忽略），但仍然是一个字符串值。

示例

1. 定义一个secret，其值为moo4ahn3ahb4phein1eingaep

secret: moo4ahn3ahb4phein1eingaep

2. 定义3个secret，其值分别为myFirstSecret, SECRET_NUMBER_2 和 3rd-secret，注意，第二个前的空格会被忽略

secret: myFirstSecret,    SECRET_NUMBER_2,3rd-secret

3. 使用环境变量，其名称为MY_SECRET

secret: ${env:MY_SECRET}

subscriptions (订阅，可选)

subscriptions属性用于为您的Prisma服务定义所有订阅webhook，其需要（至少）两条信息：

• subscriptions query定义应在哪个事件中调用函数以及payload的样子
• 一旦事件发生，通过HTTP调用的webhook的URL
• (可选)附加到发送到URL的请求的HTTP头

类型

subscriptions属性是具有以下属性的对象：

• query(必须)：subscription query的文件路径。
• webhook(必须)：关于要调用的webhook的信息（URL和可选的HTTP headers）。如果没有HTTP headers，则可以直接向该属性提供URL（请参阅下面的第一个示例）。否则，webhook会接收另一个具有url和headers属性的对象（请参阅下面的第二个示例）。

示例

1. 事件订阅没有HTTP headers。

subscriptions:
  sendWelcomeEmail:
      query: database/subscriptions/sendWelcomeEmail.graphql
      webhook: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev/sendWelcomeEmail

2. 事件订阅指定两个HTTP headers。

subscriptions:
  sendWelcomeEmail:
      query: database/subscriptions/sendWelcomeEmail.graphql
      webhook:
        url: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev/sendWelcomeEmail
        headers:
          Authorization: ${env:MY_ENDPOINT_SECRET}
          Content-Type: application/json

seed (种子数据，可选)

数据库种子是用测试数据（或初始化数据）填充服务的标准方式。

类型

seed属性为一个对象，具有以下两个属性之一：

• import：在播种服务时导入数据的说明。参考两种文件：
  • 拥有GraphQL操作的.graphql文件路径
  • 或包含以规范化数据格式（Normalized Data Format，NDF）格式的数据集的.zip文件的路径
• run：在种子服务时执行时的shell命令。这意味着不在导入范围内的更复杂的种子设置。

注意：目前不支持run。请关注此提议。

首次部署服务时，会隐式执行种子（除非使用--no-seed标志显式禁用）。请关注请求以获取其他播种工作的workflows。

示例

1. 提供包含种子突变的.graphql文件：

seed:
  import: database/seed.graphql

2. 使用NDF中的数据集引用.zip文件：

seed:
  import: database/backup.zip

3. 播种时运行node脚本：

seed:
  run: node script.js

custom (自定义，可选)

custom属性可以让你指定任何你想在你的prisma.yml其他地方重用的值。因此它没有预定义的结构。您可以使用带有self variable source的变量来引用值，例如：$ {self：custom.myVariable}。

类型

custom属性为一个对象。没有对此对象的具体要求。

示例

定义两个custom值并在subscriptions的定义中重新使用它们。

custom:
  serverlessEndpoint: https://bcdeaxokbj.execute-api.eu-west-1.amazonaws.com/dev
  subscriptionQueries: database/subscriptions/

subscriptions:
  sendWelcomeEmail:
    query: ${self:custom.subscriptionQueries}/sendWelcomeEmail.graphql
    webhook: https://${self:custom.serverlessEndpoint}/sendWelcomeEmail

hooks (钩子，可选)

hooks属性用于定义在特定命令之前或之后由Prisma CLI执行的终端命令。

当前可用的钩子如下：

• post-deploy：将在prisma deploy命令后调用，即部署后调用。

类型

hooks属性为一个对象。这些属性与当前可用的钩子的名称相匹配。

示例

以下是在执行prisma deploy后执行三项任务的示例：

1. 输出Deployment finished
2. 下载.graphqlconfig.yml中指定的db项目的GraphQL schema
3. 调用.graphqlconfig.yml中指定的代码生成

hooks:
  post-deploy:
    - echo "Deployment finished"
    - graphql get-schema --project db
    - graphql prepare

请注意，此设置假定.graphqlconfig.yml的有如下代码：

projects:
  prisma:
    schemaPath: generated/prisma.graphql
    extensions:
      prisma: prisma.yml
      prepare-binding:
        output: generated/prisma.ts
        generator: prisma-ts