本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# W3C\$1LOG\$1PARSE
<a name="sql-reference-w3c-log-parse"></a>



```
 W3C_LOG_PARSE( <character-expression>, <format-string> )
 <format-string> := '<predefined-format> | <custom-format>'
 <predefined format> :=
         COMMON
       | COMMON WITH VHOST
       | NCSA EXTENDED
       | REFERER
       | AGENT
       | IIS
 <custom-format> := [an Apache log format specifier]
```

## W3C 预定义格式
<a name="sql-reference-w3c-log-parse-predefined"></a>

指定以下 W3 C-predefined-format 名称时使用所示的格式说明符进行汇总，如以下语句所示：

```
 select stream W3C_LOG_PARSE(message, 'COMMON') r  from w3ccommon t;
```


| 格式名称 | W3C 名称 | 格式说明符 | 
| --- | --- | --- | 
|  COMMON  |  通用日志格式 (CLF)  |  %h %l %u %t "%r" %>s %b  | 
|  COMMON WITH VHOST  |  虚拟主机的通用日志格式  |  %v %h %l %u %t "%r" %>s %b  | 
|  NCSA EXTENDED  |  NCSA extended/combined 日志格式  |  %h %l %u %t "%r" %>s %b "%[Referer]i" "%[User-agent]i"  | 
|  REFERER  |  Referer 日志格式  |  %[Referer]i ---> %U  | 
|  AGENT  |  代理（浏览器）日志格式  |  %[User-agent]i  | 

## W3C 格式说明符
<a name="sql-reference-w3c-log-parse-specfics"></a>

下面列出了格式说明符。W3C\$1LOG\$1PARSE 会自动检测这些说明符，并输出每个说明符对应一列的记录。列的类型是根据说明符的可能输出自动选择的。例如，%b 表示处理 HTTP 请求时发送的字节数，因此列类型为数字。但是，对于 %B，零字节用短划线表示，强制将列类型设置为文本。注释 A 解释说明符表中显示的“...”和“<”或“>”标记的含义。

下表按命令的字母顺序列出了 W3C 格式说明符。


| 格式说明符 | 说明 | 
| --- | --- | 
|  %  |  百分号（Apache 2.0.44 及更高版本）  | 
|  %...a  |  远程 IP 地址  | 
|  %...A  |  本地 IP 地址  | 
|  %...B  |  响应大小（以字节为单位），不包括 HTTP 标头。  | 
|  %...b  |  CLF 格式的响应大小（以字节为单位），不包括 HTTP 标头，这意味着当未发送字节时，使用“-”而不是 0。  | 
|  %...[Customerdata]C  |  发送到服务器的请求中 cookie Customerdata 的内容。  | 
|  %...D  |  处理请求所花费的时间，以微秒为单位。  | 
|  %...[CUSTOMERDATA]e  |  环境变量 CUSTOMERDATA 的内容  | 
|  %...f  |  文件名  | 
|  %...h  |  远程主机  | 
|  %...H  |  请求协议  | 
|  %...[Customerdata]i  |  发送到服务器的请求中 Customerdata：标头行的内容。  | 
|  %...l  |  远程登录名（如果提供，则来自 identd）  | 
|  %...m  |  请求方法  | 
|  %...[Customerdata]n  |  来自其他模块的备注 Customerdata 的内容。  | 
|  %...[Customerdata]o  |  回复中 Customerdata：标头行的内容。  | 
|  %...p  |  处理请求的服务器的规范端口  | 
|  %...P  |  处理请求的子项的进程 ID。  | 
|  %...[format]P  |  处理请求的子项的进程 ID 或线程 ID。有效格式为 pid 和 tid。（Apache 2.0.46 及更高版本）  | 
|  %...q  |  查询字符串（如果查询字符串存在，则前面有一个“?”，否则为空字符串）  | 
|  %...r  |  请求的第一行  | 
|  %...s  |  状态。对于内部重定向的请求，这是\$1原始\$1请求的状态，而对于最后一个，是 %...>s。  | 
|  %...t  |  时间，采用通用日志格式的时间格式（标准英文格式）  | 
|  %...[format]t  |  采用指定格式表示的时间，应采用 strimmer(3) 格式。（可能已本地化）  | 
|  %...T  |  处理请求所花费的时间，以秒为单位。  | 
|  %...u  |  远程用户（来自身份验证；如果返回状态 (%s) 为 401，则可能是虚假的）  | 
|  %...U  |  请求的 URL 路径，不包括任何查询字符串。  | 
|  %...v  |  为请求提供服务的服务器 ServerName 的规范。  | 
|  %...V  |  根据 UseCanonicalName 设置的服务器名称。  | 
|  %...X  |  响应完成时的连接状态 X = 连接在响应完成前已中止。 \$1 = 连接在响应发送后可能会保持活动状态。 - = 连接在响应发送后将关闭。 （%..X 指令在 Apache 1.3 的后期版本中为 %...c， 但这与历史 ssl %...[var]c 语法相冲突。）  | 
|  :%...I:  |  收到的字节数（包括请求和标头）不能为零。您需要启用 [mod\$1logio](http://httpd.apache.org/docs/2.0/mod/mod_logio.html) 才能使用此项。  | 
|  :%...O:  |  发送的字节数（包括标头）不能为零。您需要启用 [mod\$1logio](http://httpd.apache.org/docs/2.0/mod/mod_logio.html) 才能使用此项。  | 

**注意**  <a name="noteA"></a>
一些 W3C 格式说明符显示为包含“...”指示或“<”或“>”，它们在隐藏或重定向该说明符的输出时为可选控件。“...”可以为空（如通用规范“\$1%h %u %r \$1%s %b”中所述），也可以表示包含该项目的条件。条件是 HTTP 状态代码列表，前面可能带有“\$1”，如果不满足指定的条件，则返回的列或字段将显示为“-”。  
例如，如 [Apache 文档](http://httpd.apache.org/docs/2.0/mod/mod_log_config.html)中所述，指定“%400,501[User-agent]i”将仅在发生 400 错误和 501 错误（错误请求，未实现）时记录 User-agent。类似地，“%\$1200,304,302[Referer]i”将在无法返回某种正常状态的所有请求发生时记录 Referer:。  
当已在内部重定向请求时，修饰符“<”和“>”可用于选择是应参阅原始请求，还是应参阅最终请求（分别）。默认情况下，% 指令 %s、%U、%T、%D 和 %r 查看原始请求，而所有其他指令则查看最终请求。例如，%>s 可用于记录请求的最终状态，而 %<u 可用于针对已内部重定向到未经身份验证的资源的请求来记录原始经身份验证的用户。  
出于安全考虑，从 Apache 2.0.46 开始，不可打印字符和其他特殊字符主要通过使用 \$1xhh 序列进行转义，其中 hh 代表原始字节的十六进制表示形式。此规则的例外情况是 " 和 \$1，它们通过在前面加上反斜杠进行转义，以及所有以 C 风格表示法书写的空格字符（\$1n、\$1t 等）。在 2.0.46 之前的 httpd 2.0 版本中，没有对来自 %...r、%...i 和 %...o 的字符串进行转义，因此在处理原始日志文件时需要格外小心，因为客户端本可以在日志中插入控制字符。  
此外，在 httpd 2.0 中，B 格式的字符串仅表示 HTTP 响应的大小（以字节为单位）（例如，如果连接中止或使用 SSL，则会有所不同）。对于通过网络发送到客户端的实际字节数，请使用 [mod\$1logio](http://httpd.apache.org/docs/2.0/mod/mod_logio.html) 提供的 %O 格式。

## 按函数或类别划分的 W3C 格式说明符
<a name="w2aac22c23c17c11"></a>

类别包括发送的字节数、连接状态、环境变量的内容、文件名、主机、IP、注释、协议、查询字符串、回复、请求和时间。对于标记“...”或“<”或“>”，请参阅上一个注释。


| 函数或类别 | W3C 格式说明符 | 
| --- | --- | 
|  **发送的字节数，不包括 HTTP 标头**  | 
|  未发送字节时使用“0”  |  %...B  | 
|  未发送字节时使用“-”（CLF 格式）  |  %...b  | 
|  收到的字节数（包括请求和标头）不能为零 必须启用 [mod\$1logio](http://httpd.apache.org/docs/2.0/mod/mod_logio.html) 才能使用此项。  |  :% ... I:  | 
|  发送的字节数（包括标头）不能为零 必须启用 [mod\$1logio](http://httpd.apache.org/docs/2.0/mod/mod_logio.html) 才能使用此项。  |  :%... O:  | 
|  **响应完成时的连接状态**  | 
|  连接在响应完成前已中止  |  X  | 
|  连接在响应发送后可能会保持活动状态  |  \$1  | 
|  连接在响应发送后将关闭  |  -  | 
|   %..X 指令在 Apache 1.3 的后期版本中为 %...c，但这与历史 ssl %...[var]c 语法相冲突。   | 
|  **环境变量 CUSTOMERDATA**  | 
|  内容  |  %...[CUSTOMERDATA]e  | 
|  **文件名**  |  %...f  | 
|  **主机（远程）**  |  %...h  | 
|  **协议**  |  %...H  | 
|  **IP 地址**  | 
|  远程  |  %...a  | 
|  本地  |  %...A  | 
|  **备注**  | 
|  来自其他模块的备注 Customerdata 的内容  |  %...[Customerdata]n  | 
|  **协议（请求）**  |  %...H  | 
|  **查询字符串**  如果存在查询，则在前面加上 ? 如果不存在，则为空字符串。   |  %...q  | 
|  **回复**  | 
|  Customerdata（回复中的标头行）的内容  |  %...[Customerdata]o  | 

下表列出了响应和时间类别的 W3C 格式说明符。


| 函数或类别 | W3C 格式说明符 | 
| --- | --- | 
|  **请求**  | 
|  处理请求的服务器的规范端口  |  %...p  | 
|  发送到服务器的请求中 cookie Customerdata 的内容  |  %... [Customerdata]C  | 
|  BAR（标头行）的内容  |  %... [BAR]i  | 
|  第一行已发送：  |  %...r  | 
|  处理请求所花费的时间（以微秒为单位）  |  %...D  | 
|  协议  |  %...H  | 
|  处理请求的子项的进程 ID  |  %...P  | 
|  处理请求的子项的进程 ID 或线程 ID。 有效格式为 pid 和 tid。（Apache 2.0.46 及更高版本）  |  %...[format]P  | 
|  远程登录名（如果提供，则来自 identd）  |  %...l  | 
|  远程用户：（来自身份验证；如果返回状态 (%s) 为 401，则可能是虚假的）  |  %...u  | 
|  服务请求的服务器（规范 ServerName）  |  %...v  | 
|  按 UseCanonicalName 设置划分的服务器名称  |  %...V  | 
|  请求方法  |  %...m  | 
|  返回状态  |  %s  | 
|  处理请求所花费的时间（以秒为单位）  |  %...T  | 
|  内部重定向的\$1原始\$1请求的状态  |  %...s  | 
|  上次请求的状态  |  %...>s  | 
|  请求的 URL 路径，不包括任何查询字符串  |  %...U  | 
|  **时间**  | 
|  通用日志格式的时间格式（标准英文格式）  |  %...t  | 
|  时间采用 strftime(3) 格式，可能已本地化  |  %...[format]t  | 
|  处理请求所花费的时间（以秒为单位）  |  %...T  | 

## W3C 示例
<a name="w2aac22c23c17c13"></a>

W3C\$1LOG\$1PARSE 支持访问由 W3C 兼容的应用程序（如 Apache Web 服务器）生成的日志，生成每个说明符对应一列的输出行。数据类型派生自 [Apache mod\$1log\$1config](http://httpd.apache.org/docs/2.0/mod/mod_log_config.html?#formats) 规范中列出的日志条目描述说明符。

## 示例 1
<a name="sql-reference-w3c-log-parse-info"></a>

此示例中的输入取自 Apache 日志文件，代表通用日志格式。

### Input
<a name="sql-reference-w3c-log-parse-info-input"></a>

```
(192.168.254.30 - John [24/May/2004:22:01:02 -0700]
                     "GET /icons/apache_pb.gif HTTP/1.1" 304 0),
(192.168.254.30 - Jane [24/May/2004:22:01:02 -0700]
                     "GET /icons/small/dir.gif HTTP/1.1" 304 0);
```

### DDL
<a name="sql-reference-w3c-log-parse-info-ddl"></a>

```
CREATE OR REPLACE PUMP weblog AS
        SELECT STREAM
            l.r.COLUMN1,
            l.r.COLUMN2,
            l.r.COLUMN3,
            l.r.COLUMN4,
            l.r.COLUMN5,
            l.r.COLUMN6,
            l.r.COLUMN7
        FROM (SELECT STREAM W3C_LOG_PARSE(message, 'COMMON')
              FROM "weblog_read) AS l(r);
```

### Output
<a name="sql-reference-w3c-log-parse-info-output"></a>

```
 192.168.254.30 -  John  [24/May/2004:22:01:02 -0700] GET /icons/apache_pb.gif HTTP/1.1  304  0
 192.168.254.30 -  Jane  [24/May/2004:22:01:02 -0700] GET /icons/small/dir.gif HTTP/1.1  304  0
```

### 
<a name="sql-reference-w3c-log-parse-details"></a>

FROM 子句中的 COMMON 规范是指通用日志格式 (CLF)，使用说明符 %h %l %u %t "%r" %>s %b。

[W3C 预定义的格式](https://docs.aws.amazon.com/kinesisanalytics/latest/sqlref/sql-reference-w3c-log-parse.html#sql-reference-w3c-log-parse-predefined)显示 COMMON 和其他预定义的说明符集。

FROM 子句中的 COMMON 规范是指通用日志格式 (CLF)，使用说明符 %h %l %u %t "%r" %>s %b。

下表“通用日志格式使用的说明符”列出了 COMMON 在 FROM 子句中使用的说明符。

## 通用日志格式使用的说明符
<a name="w2aac22c23c17c17"></a>


| 输出列 | 格式说明符 | 返回值 | 
| --- | --- | --- | 
|  COLUMN1  |  %h  |  远程主机的 IP 地址  | 
|  COLUMN2  |  %l  |  远程登录名  | 
|  COLUMN3  |  %u  |  远程用户  | 
|  COLUMN4  |  %t  |  时间  | 
|  COLUMN5  |  "%r"  |  请求的第一行  | 
|  COLUMN6  |  %>s  |  状态：对于内部重定向的请求， 是\$1原始\$1请求的状态 而对于最后一个，是 %...>s。  | 
|  COLUMN7  |  %b  |  发送的字节数，不包括 HTTP 标头  | 

## 示例 2
<a name="w2aac22c23c17c19"></a>

此示例中的 DDL 显示了如何重命名输出列和筛选出不需要的列。

### DDL
<a name="sql-reference-w3c-log-parse-ddl"></a>

```
    CREATE OR REPLACE VIEW "Schema1".weblogreduced AS
        SELECT STREAM CAST(s.COLUMN3 AS VARCHAR(5)) AS LOG_USER,
        CAST(s.COLUMN1 AS VARCHAR(15)) AS ADDRESS,
        CAST(s.COLUMN4 AS VARCHAR(30)) as TIME_DATES
        FROM "Schema1".weblog s;
```

### Output
<a name="sql-reference-w3c-log-parse-output"></a>

```
    +----------+-----------------+--------------------------------+
    | LOG_USER |     ADDRESS     |           TIME_DATES           |
    |          |                 |                                |
    +----------+-----------------+--------------------------------+
    | Jane     | 192.168.254.30  | [24/May/2004:22:01:02 -0700]   |
    |          |                 |                                |
    | John     | 192.168.254.30  | [24/May/2004:22:01:02 -0700]   |
    +----------+-----------------+--------------------------------+
```

## W3C 自定义格式
<a name="w2aac22c23c17c21"></a>

通过直接命名说明符而不是使用“COMMON”名称可以生成相同的结果，如下所示：

```
    CREATE OR REPLACE FOREIGN STREAM schema1.weblog
        SERVER logfile_server
        OPTIONS (LOG_PATH '/path/to/logfile',
                 ENCODING 'UTF-8',
                 SLEEP_INTERVAL '10000',
                 MAX_UNCHANGED_STATS '10',
                 PARSER 'W3C',
                 PARSER_FORMAT '%h %l %u %t \"%r\" %>s %b');
    or
     CREATE FOREIGN STREAM "Schema1".weblog_read
     SERVER "logfile_server"
     OPTIONS (log_path '/path/to/logfile',
     encoding 'UTF-8',
     sleep_interval '10000',
     max_unchanged_stats '10');
     CREATE OR REPLACE VIEW "Schema1".weblog AS
        SELECT STREAM
            l.r.COLUMN1,
            l.r.COLUMN2,
            l.r.COLUMN3,
            l.r.COLUMN4,
            l.r.COLUMN5,
            l.r.COLUMN6
        FROM (SELECT STREAM W3C_LOG_PARSE(message, '%h %l %u %t \"%r\" %>s %b')
              FROM "Schema1".weblog_read) AS l(r);
```

**注意**  
如果您将 %t 更改为 [%t]，则日期列包含以下内容：  

```
        24/May/2004:22:01:02 -0700
```
（而不是 `[24/May/2004:22:01:02 -0700]`）