组织列表清单引用¶

作为提供商，您可以使用组织列表在组织内安全地共享数据产品。要以编程方式创建组织列表，需要使用 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
locations:
  - # Optional list of regions to share into.
auto_fulfillment:
  - # Required when the target accounts are outside the provider's region, otherwise optional.

Copy

组织列表字段¶

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

组织列表前缀¶

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

: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
. . .

Copy

`listing_terms`¶

定义列表的服务条款。

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

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

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

备注

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

`listing_terms` 示例¶

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

Copy

`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"
. . .

Copy

`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'";
. . .

Copy

`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

Copy

`organization_targets`¶

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

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

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

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

要么：

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

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

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

`organization_target` 示例¶

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

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

. . .
organization_targets:
   discovery:
   - all_accounts : true
   access:
   - all_accounts : true
. . .

Copy

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

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

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

Copy

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

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

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

Copy

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

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

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

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

Copy

`support_contact`¶

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

指定 discovery 字段时为必填。

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

Copy

`approver_contact`¶

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

指定 discovery 字段时为必填。

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

Copy

`locations`¶

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

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

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

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

组织列表清单引用¶