...

パッケージ url

import "net/url"
概要
目次

概要 ▾

url パッケージは, URL を解析し,クエリエスケープを実装します。

目次 ▾

func PathEscape(s string) string
func PathUnescape(s string) (string, error)
func QueryEscape(s string) string
func QueryUnescape(s string) (string, error)
type Error
    func (e *Error) Error() string
    func (e *Error) Temporary() bool
    func (e *Error) Timeout() bool
    func (e *Error) Unwrap() error
type EscapeError
    func (e EscapeError) Error() string
type InvalidHostError
    func (e InvalidHostError) Error() string
type URL
    func Parse(rawurl string) (*URL, error)
    func ParseRequestURI(rawurl string) (*URL, error)
    func (u *URL) EscapedPath() string
    func (u *URL) Hostname() string
    func (u *URL) IsAbs() bool
    func (u *URL) MarshalBinary() (text []byte, err error)
    func (u *URL) Parse(ref string) (*URL, error)
    func (u *URL) Port() string
    func (u *URL) Query() Values
    func (u *URL) RequestURI() string
    func (u *URL) ResolveReference(ref *URL) *URL
    func (u *URL) String() string
    func (u *URL) UnmarshalBinary(text []byte) error
type Userinfo
    func User(username string) *Userinfo
    func UserPassword(username, password string) *Userinfo
    func (u *Userinfo) Password() (string, bool)
    func (u *Userinfo) String() string
    func (u *Userinfo) Username() string
type Values
    func ParseQuery(query string) (Values, error)
    func (v Values) Add(key, value string)
    func (v Values) Del(key string)
    func (v Values) Encode() string
    func (v Values) Get(key string) string
    func (v Values) Set(key, value string)

パッケージファイル

url.go

func PathEscape 1.8

func PathEscape(s string) string

PathEscape は文字列をエスケープするため, URL パスセグメント内に安全に配置でき,必要に応じて特殊文字 (/ を含む) を %XX シーケンスに置き換えます。

func PathUnescape 1.8

func PathUnescape(s string) (string, error)

PathUnescape は PathEscape の逆変換を行い, "%AB" という形式の 3 バイトのエンコードされた各部分文字列を 16 進数のデコードされたバイト 0xAB に変換します。 % の後に 2 桁の 16 進数字が続かない場合はエラーを返します。

PathUnescape は QueryUnescape と同じですが, '+' から ' ' (スペース) へのエスケープ解除はしません。

func QueryEscape

func QueryEscape(s string) string

QueryEscape は文字列をエスケープするので, URL クエリ内に安全に配置できます。

func QueryUnescape

func QueryUnescape(s string) (string, error)

QueryUnescape は QueryEscape の逆変換を行い, "%AB" という形式の 3 バイトでエンコードされた各部分文字列を 16 進数でデコードされたバイト 0xAB に変換します。 % の後に 2 桁の 16 進数字が続かない場合はエラーを返します。

type Error

Error は,エラーとそれを引き起こした操作および URL を報告します。

type Error struct {
    Op  string
    URL string
    Err error
}

func (*Error) Error

func (e *Error) Error() string

func (*Error) Temporary 1.6

func (e *Error) Temporary() bool

func (*Error) Timeout 1.6

func (e *Error) Timeout() bool

func (*Error) Unwrap 1.13

func (e *Error) Unwrap() error

type EscapeError

type EscapeError string

func (EscapeError) Error

func (e EscapeError) Error() string

type InvalidHostError 1.6

type InvalidHostError string

func (InvalidHostError) Error 1.6

func (e InvalidHostError) Error() string

type URL

URL は,解析された URL (厳密には URI 参照) を表します。

表される一般的な形式は次のとおりです。

[scheme:][//[userinfo@]host][/]path[?query][#fragment]

スキームの後にスラッシュで始まらない URL は,次のように解釈されます。

scheme:opaque[?query][#fragment]

Path フィールドはデコードされた形式で保存されることに注意する : /%47%6f%2f は /Go/ になります。その結果,パス内のどのスラッシュが未加工 URL のスラッシュであり,どのスラッシュが %2f であったかを判別することは不可能です。この区別が重要になることはめったにありませんが,その場合,コードは RawPath を使用する必要があります。 RawPath は,デフォルトのエンコーディングが Path と異なる場合にのみ設定されるオプションフィールドです。

URL の String メソッドは, EscapedPath メソッドを使用してパスを取得します。詳細については, EscapedPath メソッドを参照する。

type URL struct {
    Scheme     string
    Opaque     string    // エンコードされた不透明データ
    User       *Userinfo // ユーザー名とパスワードの情報
    Host       string    // host または host:port
    Path       string    // パス (相対パスは先頭のスラッシュを省略することができます)
    RawPath    string    // エンコードされたパスのヒント (EscapedPath メソッドを参照); added in Go 1.5
    ForceQuery bool      // RawQuery が空の場合でも,クエリ ('?') を追加します。; added in Go 1.7
    RawQuery   string    // '?' なしでエンコードされたクエリ値
    Fragment   string    // 参照用のフラグメント, '#' なし
}

コード:

u, err := url.Parse("http://bing.com/search?q=dotnet")
if err != nil {
    log.Fatal(err)
}
u.Scheme = "https"
u.Host = "google.com"
q := u.Query()
q.Set("q", "golang")
u.RawQuery = q.Encode()
fmt.Println(u)

出力:

https://google.com/search?q=golang

例 (Roundtrip)

コード:

// Parse + String は元のエンコーディングを保持します。
u, err := url.Parse("https://example.com/foo%2fbar")
if err != nil {
    log.Fatal(err)
}
fmt.Println(u.Path)
fmt.Println(u.RawPath)
fmt.Println(u.String())

出力:

/foo/bar
/foo%2fbar
https://example.com/foo%2fbar

func Parse

func Parse(rawurl string) (*URL, error)

解析は rawurl を URL 構造に解析します。

rawurl は相対パス (ホストなしのパス) でも絶対パス (スキームから始まる) でも構いません。 スキームなしでホスト名とパスを解析しようとすることは無効ですが,あいまいさを解析するために必ずしもエラーを返すとは限りません。

func ParseRequestURI

func ParseRequestURI(rawurl string) (*URL, error)

ParseRequestURI は, rawurl を URL 構造に解析します。 rawurl は HTTP リクエストで受信されたと想定しているため, rawurl は絶対 URI または絶対パスとしてのみ解釈されます。 文字列 rawurl は #fragment 接尾辞を持たないと仮定されます。 (Web ブラウザは URL を Web サーバに送信する前に #fragment を取り除きます。)

func (*URL) EscapedPath 1.5

func (u *URL) EscapedPath() string

EscapedPath は, u.Path のエスケープ形式を返します。 一般的に,任意のパスには複数のエスケープ形式があります。 EscapedPath は, u.Path の有効なエスケープである場合, u.RawPath を返します。 そうでなければ, EscapedPath は u.RawPath を無視し,それ自体でエスケープフォームを計算します。 String および RequestURI メソッドは EscapedPath を使用してそれらの結果を構築します。 一般に,コードは u.RawPath を直接読み取るのではなく EscapedPath を呼び出す必要があります。

コード:

u, err := url.Parse("http://example.com/path with spaces")
if err != nil {
    log.Fatal(err)
}
fmt.Println(u.EscapedPath())

出力:

/path%20with%20spaces

func (*URL) Hostname 1.8

func (u *URL) Hostname() string

Hostname は u.Host を返し,有効なポート番号があれば削除します。

リテラル IPv6 アドレスがそうであるように,結果が角括弧で囲まれている場合,角括弧は結果から削除されます。

コード:

u, err := url.Parse("https://example.org:8000/path")
if err != nil {
    log.Fatal(err)
}
fmt.Println(u.Hostname())
u, err = url.Parse("https://[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:17000")
if err != nil {
    log.Fatal(err)
}
fmt.Println(u.Hostname())

出力:

example.org
2001:0db8:85a3:0000:0000:8a2e:0370:7334

func (*URL) IsAbs

func (u *URL) IsAbs() bool

IsAbs は URL が絶対パスかどうかを報告します。 絶対とは,空でない方式であることを意味します。

コード:

u := url.URL{Host: "example.com", Path: "foo"}
fmt.Println(u.IsAbs())
u.Scheme = "http"
fmt.Println(u.IsAbs())

出力:

false
true

func (*URL) MarshalBinary 1.8

func (u *URL) MarshalBinary() (text []byte, err error)

コード:

u, _ := url.Parse("https://example.org")
b, err := u.MarshalBinary()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", b)

出力:

https://example.org

func (*URL) Parse

func (u *URL) Parse(ref string) (*URL, error)

Parse は,受信者のコンテキストで URL を解析します。 渡される URL は相対的または絶対的なものです。 Parse は nil を返し,解析に失敗すると err を返します。 それ以外の場合,戻り値は ResolveReference と同じです。

コード:

u, err := url.Parse("https://example.org")
if err != nil {
    log.Fatal(err)
}
rel, err := u.Parse("/foo")
if err != nil {
    log.Fatal(err)
}
fmt.Println(rel)
_, err = u.Parse(":foo")
if _, ok := err.(*url.Error); !ok {
    log.Fatal(err)
}

出力:

https://example.org/foo

func (*URL) Port 1.8

func (u *URL) Port() string

Port は,先頭のコロンなしで u.Host のポート部分を返します。

u.Host に有効な数値ポートが含まれていない場合, Port は空の文字列を返します。

コード:

u, err := url.Parse("https://example.org")
if err != nil {
    log.Fatal(err)
}
fmt.Println(u.Port())
u, err = url.Parse("https://example.org:8080")
if err != nil {
    log.Fatal(err)
}
fmt.Println(u.Port())

出力:

8080

func (*URL) Query

func (u *URL) Query() Values

Query は RawQuery を解析し,対応する値を返します。 誤った形式の値のペアは黙って破棄されます。 エラーをチェックするには ParseQuery を使います。

コード:

u, err := url.Parse("https://example.org/?a=1&a=2&b=&=3&&&&")
if err != nil {
    log.Fatal(err)
}
q := u.Query()
fmt.Println(q["a"])
fmt.Println(q.Get("b"))
fmt.Println(q.Get(""))

出力:

[1 2]

3

func (*URL) RequestURI

func (u *URL) RequestURI() string

RequestURI は, u に対する HTTP リクエストで使用されるエンコードされたパス ?query または opaque? クエリ文字列を返します。

コード:

u, err := url.Parse("https://example.org/path?foo=bar")
if err != nil {
    log.Fatal(err)
}
fmt.Println(u.RequestURI())

出力:

/path?foo=bar

func (*URL) ResolveReference

func (u *URL) ResolveReference(ref *URL) *URL

ResolveReference は, RFC 3986 Section 5.2 に従って,絶対ベース URI u から絶対 URI への URI 参照を解決します。 URI 参照は相対的または絶対的なものです。 返された URL がベースまたは参照のいずれかと同一であっても, ResolveReference は常に新しい URL インスタンスを返します。 ref が絶対 URL の場合, ResolveReference は base を無視して ref のコピーを返します。

コード:

u, err := url.Parse("../../..//search?q=dotnet")
if err != nil {
    log.Fatal(err)
}
base, err := url.Parse("http://example.com/directory/")
if err != nil {
    log.Fatal(err)
}
fmt.Println(base.ResolveReference(u))

出力:

http://example.com/search?q=dotnet

func (*URL) String

func (u *URL) String() string

String は, URL を有効な URL 文字列に再組み立てします。 結果の一般形式は,次のいずれかです。

scheme:opaque?query#fragment
scheme://userinfo@host/path?query#fragment

u.Opaque が空でない場合, String は最初の形式を使用します。 それ以外の場合は 2 番目の形式を使用します。 host 内の ASCII 以外の文字はエスケープされます。 パスを取得するために, String は u.EscapedPath() を使用します。

2 番目の形式では,以下の規則が適用されます。

- u.Scheme が空の場合, scheme: は省略されます。
- u.User が nil の場合,userinfo@ は省略されます。
- u.Host が空の場合, host/ は省略されます。
- u.Scheme と u.Host が空で, u.User が nil の場合,scheme://userinfo@host/ 全体が省略されます。
- u.Host が空ではなく, u.Path が / で始まっている場合, host/path という形式では独自の / は追加されません。
- u.RawQuery が空の場合, ?query は省略されます。
- u.Fragment が空の場合, #fragment は省略されます。

コード:

u := &url.URL{
    Scheme:   "https",
    User:     url.UserPassword("me", "pass"),
    Host:     "example.com",
    Path:     "foo/bar",
    RawQuery: "x=1&y=2",
    Fragment: "anchor",
}
fmt.Println(u.String())
u.Opaque = "opaque"
fmt.Println(u.String())

出力:

https://me:pass@example.com/foo/bar?x=1&y=2#anchor
https:opaque?x=1&y=2#anchor

func (*URL) UnmarshalBinary 1.8

func (u *URL) UnmarshalBinary(text []byte) error

コード:

u := &url.URL{}
err := u.UnmarshalBinary([]byte("https://example.org/foo"))
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%s\n", u)

出力:

https://example.org/foo

type Userinfo

Userinfo 型は, URL のユーザー名とパスワードの詳細を不変にカプセル化したものです。 既存の Userinfo 値は,ユーザ名セット (RFC2396 で許可されているように潜在的に空) ,およびオプションでパスワードを持つことが保証されています。

type Userinfo struct {
    // エクスポートされていないフィールドがあります
}

func User

func User(username string) *Userinfo

User は,指定されたユーザー名を含み,パスワードが設定されていない Userinfo を返します。

func UserPassword

func UserPassword(username, password string) *Userinfo

UserPassword は,指定されたユーザー名とパスワードを含む Userinfo を返します。

この機能は,従来の Web サイトでのみ使用してください。 RFC 2396 では, Userinfo をこのように解釈することは推奨されていません。 "URI などの認証情報を平文で渡すことは,ほとんどの場合セキュリティ上のリスクがあることが証明されているためです " 。

func (*Userinfo) Password

func (u *Userinfo) Password() (string, bool)

Password は,設定されている場合と設定されているかどうかにかかわらず,パスワードを返します。

func (*Userinfo) String

func (u *Userinfo) String() string

String は,エンコードされたユーザ info 情報を "username[:password]" の標準形式で返します。

func (*Userinfo) Username

func (u *Userinfo) Username() string

Username はユーザー名を返します。

type Values

Values は文字列キーを値のリストにマップします。 通常,クエリパラメータとフォーム値に使用されます。 http.Header マップとは異なり, Values マップのキーでは大文字と小文字が区別されます。

type Values map[string][]string

コード:

v := url.Values{}
v.Set("name", "Ava")
v.Add("friend", "Jess")
v.Add("friend", "Sarah")
v.Add("friend", "Zoe")
// v.Encode() == "name=Ava&friend=Jess&friend=Sarah&friend=Zoe"
fmt.Println(v.Get("name"))
fmt.Println(v.Get("friend"))
fmt.Println(v["friend"])

出力:

Ava
Jess
[Jess Sarah Zoe]

func ParseQuery

func ParseQuery(query string) (Values, error)

ParseQuery は URL エンコードされたクエリ文字列を解析し,各キーに指定された値をリストしたマップを返します。 ParseQuery は常に,見つかったすべての有効なクエリパラメータを含む非 nil マップを返します。 err は,もしあれば,発生した最初のデコードエラーを記述します。

Query はアンパサンドまたはセミコロンで区切られた key=value 設定のリストであることが期待されています。 等号のない設定は,空の値に設定されたキーとして解釈されます。

コード:

m, err := url.ParseQuery(`x=1&y=2&y=3;z`)
if err != nil {
    log.Fatal(err)
}
fmt.Println(toJSON(m))

出力:

{"x":["1"], "y":["2", "3"], "z":[""]}

func (Values) Add

func (v Values) Add(key, value string)

Add は key に value を追加します。 key に関連付けられている既存の値に追加されます。

func (Values) Del

func (v Values) Del(key string)

Del は key に関連した値を削除します。

func (Values) Encode

func (v Values) Encode() string

Encode は,値をキーでソートされた "URL エンコード" 形式 ("bar=baz&foo=quux") にエンコードします。

func (Values) Get

func (v Values) Get(key string) string

Get は,key に関連付けられている最初の値を取得します。 key に関連付けられている値がない場合, Get は空の文字列を返します。 複数の値にアクセスするには,マップを直接使用してください。

func (Values) Set

func (v Values) Set(key, value string)

Set は key を value に設定します。 既存の値を置き換えます。