组织列表清单引用¶

作为提供商，您可以使用组织列表在组织内安全地共享数据产品。要以编程方式创建组织列表，需要使用 YAML (https://yaml.org/spec/ (https://yaml.org/spec/)) 编写的清单。下面介绍清单的整体格式以及清单的每个字段，包括细节和示例。

组织列表字段是较大列表清单引用的一部分。要以编程方式添加或修改组织列表字段，请使用 ALTER LISTING 和 DESCRIBE LISTING 命令查找和修改列表清单。

组织列表清单¶

备注

组织列表字段有两种：

可选 – 组织列表的可选字段。
必填 – 组织列表的必填字段。

组织列表列表的一般格式为：

#
# Organization listing manifest
#
title: <Required listing title>
description: <listing description>
resources: <optional listing resources>
listing_terms: <optional listing terms>
data_dictionary: <optional data dictionary>
usage_examples: <optional usage examples>
data_attributes: <optional data attributes>
organization_profile: <Optional custom organization profile. Default "INTERNAL">
organization_targets:
  - # Required
support_contact: "<support email address>"
  - # Required
approver_contact: "<approver email address"
  - # Required when the organization_targets includes the organization_targets.discover field
request_approval_type:
  - # Optional. Can be REQUEST_AND_APPROVE_IN_SNOWFLAKE or REQUEST_AND_APPROVE_OUTSIDE_SNOWFLAKE.
locations:
  - # Optional list of regions to share into.
auto_fulfillment:
  - # Required when the target accounts are outside the provider's region, otherwise optional.

组织列表字段¶

组织列表清单包括前缀，后跟是一组必填和可选字段。

组织列表前缀¶

每个组织列表清单采用以下字段开头：

:code:`title`（字符串，必填，最大长度 110）：列表标题。
:code:`description`（字符串，可选，最大长度 7500）：列表描述。支持 Markdown 语法。
:code:`resources`（字符串，可选）：列表资源。
:code:`listing_terms`（带有子字段的父字段，可选）：列表的条款信息。
:code:`organization_profile`（字符串，可选）：可选的自定义组织配置文件。默认为 INTERNAL（如果未指定）。

`resources`¶

列表资源。

可选 resources 字段包含以下名称/值对：

resources.documentation`（字符串，必填）：指向您网站上的页面的完全限定链接，其中包含有关列表的更详细文档。必须以 :code:`http 或 https 开头。
:code:`resources.media`（字符串，可选）：指向列表的不公开或公开 YouTube 视频的完全限定链接。

有关您可以在此字段中包含的信息类型的更多信息，请参阅详细信息。

`resources` 示例¶

. . .
resources:
  documentation: https://www.example.com/documentation/
  media: https://www.youtube.com/watch?v=MEFlT3dc3uc
. . .

`listing_terms`¶

定义列表的服务条款。

可选 listing_terms 字段包含以下名称/值对：

listing_terms.type
- CUSTOM – 仅支持 CUSTOM。如果已指定 listing_terms.type，则您还必须为 listing_terms.link 指定值。
listing_terms.link：指向提供商列表条款的完全限定链接，必须以 http 或 https 开头。

有关更多信息，请参阅基本信息中表内的 服务条款。

备注

使用者可以以编程方式接受列表条款。如需更多信息，请联系 Snowflake 支持部门。

`listing_terms` 示例¶

. . .
listing_terms:
  type: "CUSTOM"
  link: "http://example.com/my/listing/terms"
. . .

`data_dictionary`¶

可选 data_dictionary 字段提供有关列表中对象的数据预览和列类型的信息。

data_dictionary 字段包含由最多五个数据字典条目组成的列表：

data_dictionary.featured`（使用 :code:`data_dictionary 时为必填）：必须是“featured”。
data_dictionary.featured.database`（使用 :code:`data_dictionary 时为必填）：数据库名称。
data_dictionary.featured.objects`（使用 :code:`data_dictionary 时为必填）：包含以下名称/值对：
- :code:`name`（字符串，必填）：对象名称。
- :code:`schema`（字符串，必填）：与数据字典相关联的架构。
- :code:`domain`（必填）：
  
  以下其中一项：
  - DATABASE
  - SCHEMA
  - TABLE
  - VIEW
  - EXTERNAL_TABLE
  - MATERIALIZED_VIEW
  - DIRECTORY_TABLE
  - FUNCTION
  - COLUMN

有关更多信息，请参阅数据产品 – 数据字典。

`data_dictionary` 示例¶

. . .
data_dictionary:
 featured:
    database: "WEATHERDATA"
    objects:
       - name: "GLOBAL_WEATHER"
         schema: "PUBLIC"
         domain: "TABLE"
       - name: "GLOBAL_WEATHER_REPORT"
         schema: "PUBLIC"
         domain: "TABLE"
. . .

`usage_examples`¶

可选 usage_examples 字段包含以下名称/值对的列表：

:code:`usage.title`（字符串，必填）：使用示例标题。最大长度为 110 个字符。
:code:`usage.description`（字符串，可选）：使用示例的描述。最大长度为 300 个字符。
:code:`usage.query`（字符串，必填）：与使用示例相关联的查询。最大长度为 30000 个字符。

有关更多信息，请参阅示例 SQL 查询。

`usage_examples` 示例¶

. . .
usage_examples:
  - title: "Return all weather for the US"
    description: "Example of how to select weather information for the United States"
    query: "select * from weather where country_code='USA'";
. . .

`data_attributes`¶

数据属性为使用者提供列表信息。

可选 data_attributes 字段包含以下名称/值对：

:code:`data_attributes.refresh_rate`（必填）

以下其中一项：指定数据产品在 Snowflake 中的更新频率。
- CONTINUOUSLY
- HOURLY
- DAILY
- WEEKLY
- MONTHLY
- QUARTERLY
- ANNUALLY
- STATIC
:code:`data_attributes.geography`（必填）：

指定数据产品的地理信息。
- :code:`granularity`（字符串，必填）
  
  数据集的地理覆盖范围。
  
  以下其中一项：
  - LATITUDE_LONGITUDE
  - ADDRESS
  - POSTAL_CODE
  - CITY
  - COUNTY
  - STATE
  - COUNTRY
  - REGION_CONTINENT
- :code:`geo_option`（字符串，必填）
  
  以下其中一项：
  - NOT_APPLICABLE
  - GLOBAL
  - COUNTRIES
- coverage`（是否必填取决于选择的 :code:`geo_option）：
  - :code:`states`（州列表），包含有效美国州名的任意列表。
  Or
  - :code:`continents`（大洲列表）：
    
    以下任何一项：
    
    ASIA
    
    EUROPE
    
    AFRICA
    
    NORTH AMERICA
    
    SOUTH AMERICA
    
    OCEANIA
    
    ANTARCTICA
- :code:`time`（必填）：
  
  指定数据产品的时间段。
  - :code:`granularity`（必填）
  以下其中一项：
  - EVENT_BASED
  - HOURLY
  - DAILY
  - WEEKLY
  - MONTHLY
  - YEARLY
  - :code:`time_range`（必填），包含以下名称/值对：
    
    :code:`time_frame`（必填）
    
    以下其中一项：
    
    NEXT
    
    LAST
    
    BETWEEN
    
    :code:`unit`（必填）
    
    以下其中一项：
    
    DAYS
    
    WEEKS
    
    MONTHS
    
    YEARS
    
    value`（当 :code:`time_frame 为 NEXT/LAST 时为必填，整型）。范围是 1 到 100。
    
    start_time`（当 :code:`time_frame 为 BETWEEN 时为必填，字符串日期）。数据产品的开始时间。格式为 MM-DD-YYYY。
    
    end_time`（当 :code:`time_frame 为 BETWEEN 时为必填，字符串日期），格式为 MM-DD-YYYY。

有关数据产品属性的更多信息，请参阅数据产品 – 属性。

`data_attributes` 示例¶

. . .
data_attributes:
  refresh_rate: DAILY
  geography:
    granularity:
      - REGION_CONTINENT
    geo_option: COUNTRIES
    coverage:
      continents:
        ASIA:
          - INDIA
          - CHINA
        NORTH AMERICA:
          - UNITED STATES
          - CANADA
        EUROPE:
          - UNITED KINGDOM
    time:
      granularity: MONTHLY
      time_range:
        time_frame: LAST
        unit: MONTHS
        value: 6

`organization_targets`¶

必填 organization_targets 字段定义谁可以发现和访问列表。

包含 discovery 和 access 字段，必须指定其中一个字段。

discovery: 未指定 access 时，为必填，否则为可选。定义谁可以发现列表。当此字段不存在时，所有账户均无法查看该列表。
access: 未指定 discovery 时，为必填，否则为可选。定义谁可以访问列表。

discovery 和 access，都包含相同的子字段。

要么：

all_internal_accounts : {true | false}: 如果为 true，则所有内部账户都可以查找或访问列表。如果为 false，则任何账户都无法查找或访问该列表。
或者是一个账户数组，后跟指定账户中的可选 roles 数组。: - account: "<account_name>"

当 roles 存在时，它会指定账户中可以访问或发现列表的角色列表。例如：

. . . roles: [ 'role1','role2'] . . .

`organization_target` 示例¶

以下示例显示 discovery 和 access 字段的各种组合。

组织中的所有内部账户都可以发现和访问列表¶

. . .
organization_targets:
   discovery:
   - all_internal_accounts : true
   access:
   - all_internal_accounts : true
. . .

可发现，但只有有限的账户可以访问¶

组织内的所有内部账户都可以发现列表，但只有 finance 账户才能访问列表。

. . .
organization_targets:
   discovery:
   - all_internal_accounts : true
   access:
   - account: 'finance'
. . .

可发现，但只有指定账户可以访问¶

组织内的所有内部账户都可以发现列表，但只有 finance 或 credit 账户中的账户才能访问列表。

. . .
organization_targets:
   discovery:
   - all_internal_accounts : true
   access:
   - account: 'finance'
   - account: 'credit'
. . .

可发现，但只有有限的账户和特定角色可以访问¶

组织内的所有内部账户都可以发现列表，但只有 finance 账户中具有 accounting 或 debit 角色的账户才能访问列表。

. . .
organization_targets:
    discovery:
    - all_internal_accounts : true
    access:
    - account: 'finance'

      roles: [ 'accounting','debit']
. . .

`support_contact`¶

与列表相关联的支持信息的电子邮件地址。

已指定 discovery 字段时，为必填。

. . .
support_contact: "support@exampledomain.com"
. . .

`approver_contact`¶

列表批准者的电子邮件地址。

已指定 discovery 字段时，为必填。

. . .
  approver_contact: "approver@exampledomain.com"
. . .

`request_approval_type`¶

Define whether approval requests and approvals will happen inside or outside of Snowflake. Specify one of the following values:

NULL
REQUEST_AND_APPROVE_IN_SNOWFLAKE indicates access requests are submitted and approved within the Snowflake environment.
REQUEST_AND_APPROVE_OUTSIDE_SNOWFLAKE indicates the provider manages access request submissions and approvals independently.

The value for external listings is always NULL.

. . .
  request_approval_type: "REQUEST_AND_APPROVE_IN_SNOWFLAKE"
. . .

`locations`¶

指定可以发现或访问列表的可选 locations。

已指定 locations 时，access_regions 字段为必填，且它必须包含以下子字段之一：

ALL – 所有地区都可以发现或访问列表。
带有 PUBLIC 前缀的区域名称数组可以发现或访问列表。例如 access_regions: - name: PUBLIC.AWS_US_WEST_2。
```
. . .
locations:
  access_regions:
  - name: "<names | ALL>"
. . .
```

有关区域的完整列表，请参阅 SHOW REGIONS。

`auto_fulfillment`¶

Cross-Cloud Auto-fulfillment allows the data product associated with a listing to be automatically fulfilled to other Snowflake regions. The auto_fulfillment field defines how that auto-fulfillment takes place.

For more information on Cross-Cloud Auto-fulfillment, see 列表的自动履行.

Auto-fulfillment is only required if you're sharing data to multiple regions. Do not enable it if you are sharing to accounts in the same region.

If you share data across multiple regions, the auto_fulfillment is:

Required if your data product is an application package.
Required if your data product is shared through a private listing.
Recommended if your data product is shared through a public listing.

Contains the following name value pairs:

auto_fulfillment.refresh_schedule
- <num> MINUTE - Number of minutes. Minimum 10 minutes, maximum 8 days, or 11520 minutes.
  
  If refresh_type is specified as SUB_DATABASE_WITH_REFERENCE_USAGE, do not include this setting. The refresh schedule for application packages must be defined at the account level and cannot specified at the listing level.
  
  For more information see 设置账户级刷新间隔.
USING CRON <expression> - Defines the data product auto-fulfillment refresh schedule.

The syntax for USING CRON and REPLICATION SCHEDULE are the same. See 参数.
auto_fulfillment.refresh_type (required when using auto_fulfillment): Must be one of -
- SUB_DATABASE - database replication (object level) - recommended.
- SUB_DATABASE_WITH_REFERENCE_USAGE - application package.
- FULL_DATABASE - database replication (for the entire database). (Deprecated.)
auto_fulfillment.refresh_schedule_override (optional): Overrides the defined update refresh frequency for all listings that use the same database. When this value is FALSE, listing updates fail when multiple listings sharing the same database have different refresh frequencies.
- TRUE - enables the refresh frequency override.
- FALSE - (default) disables the refresh frequency override.

`auto_fulfillment.refresh_schedule` examples¶

The following example refreshes the data product associated with a listing every 10 minutes:

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_schedule: 10 MINUTE
  refresh_type: SUB_DATABASE
. . .

The following example refreshes the data product associated with a listing on specific days and times in specific regions:

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_schedule: USING CRON  0 17 * * MON-FRI Europe/London
  refresh_type: SUB_DATABASE
. . .

The following example enables the refresh frequency override for listings that share the same database but have different refresh frequencies:

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_schedule: 10 MINUTE
  refresh_type: SUB_DATABASE
  refresh_schedule_override: TRUE
. . .

Snowflake Native App `auto_fulfillment` example¶

SUB_DATABASE_WITH_REFERENCE_USAGE can only be used with application packages and cannot be combined with auto_fulfillment.refresh_schedule.

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_type: SUB_DATABASE_WITH_REFERENCE_USAGE
. . .

Object level `auto_fulfillment` example¶

. . .
listing_terms: . . .
. . .
auto_fulfillment:
  refresh_type: SUB_DATABASE
. . .

组织列表清单引用¶